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.