User primitives
VA Smalltalk supports three syntaxes for user primitives:
messagePattern
<primitive: primitiveName>
...fail code...
messagePattern
<primitive: 'sharedLibrary':functionName>
...fail code...
messagePattern
<primitive: 'sharedLibrary':functionNumber>
...fail code...
The first syntax looks up the primitive in the user primitive table. primitiveName is an alphanumeric identifier. It is not surrounded by quotation marks. For example:
add: a and: b
<primitive: add2Numbers>
^self primitiveFailed
The other two syntaxes look up a user primitive function in a shared library, either by name or by number. The sharedLibrary, functionName, and functionNumber fields have the same syntax and function as those in a PlatformFunction. sharedLibrary must be surrounded by quotes. functionName has no quotes. For example:
myFunc: arg1
<primitive: 'MYLIB':myFunc>
^self primitiveFailed
The user primitive acts the same way whether it is in the user primitive table or in a shared library. If the primitive succeeds, the object returned from the primitive is returned from the method. If the primitive fails, the fail code (the rest of the code in the method) is run. If no fail code is provided, self is returned on primitive failure. The suggested default fail code is ^self primitiveFailed. It generates a walkback describing the reason for the failure.
In C, a user primitive function is defined as:
EsUserPrimitive(functionName)
{
...your code...
}
Within the primitive, the following are defined:
EsPrimVMContext
Wherever a vmContext parameter is required when calling a function, pass this value.
EsPrimReceiver
The receiver of the primitive method. It has type EsObject.
EsPrimArgumentCount
The number of arguments (not including the receiver) that were passed to the primitive method.
EsPrimArgument(n)
The nth argument (an EsObject) of the primitive method. The value of n is not validated.
If the primitive fails, use
EsPrimFail(errorCode, argumentNumber).
errorCode. is one of the
EsPrimErr values defined in
Table 39.
argumentNumber is the index of the argument in which the error occurred. If the error occurred in the receiver, use
EsPrimArgNumSelf. If the error occurred in no particular argument (for example, an
EsAllocateObject failed), use
EsPrimArgNumNoArg.
EsPrimFail returns from the user primitive function.
If the primitive succeeds, use EsPrimSucceed(returnObject). returnObject must be an EsObject. EsPrimSucceed returns from the user primitive function.
Last modified date: 01/29/2015