Programmer's Reference

Functions available in user primitives

This section defines the functions available in user primitives:

Object allocation

These functions enable users to allocate new objects from within a user primitive.

EsObject EsAllocateObject(EsVMContext vmContext, EsBehavior allocateClass, U_32 size, U_32 saves, EsObject ** saveList)
Returns a new, initialized object of class allocateClass with size indexable instance variables. Pass 0 for saves and NULL for saveList. The instance variables of pointer objects are initialized to nil. All other objects are initialized to 0.

Error cases: If the object could not be allocated for any reason, returns NULL.

Smalltalk equivalent: allocateClass new: size

Side effects: This operation can cause a garbage collection.

EsObject EsAllocateFixedObject(EsVMContext vmContext, EsBehavior allocateClass, U_32 size, U_32 saves, EsObject ** saveList)
Same as EsAllocateObject, except the object is allocated in fixed space. This means that the object does not move during a garbage collect.

Error cases: If the object could not be allocated for any reason, returns NULL.

Smalltalk equivalent: (allocateClass new: size) makeFixed

Sending messages

This function enables users to send a message from within a user primitive and retrieve the result.

U_32 EsSendMessage(EsVMContext vmContext, EsObject * returnObject, EsObject receiver, EsObject selector, U_32 argumentCount, ...)
Calls back into the IBM Smalltalk interpreter by sending a message. returnObject is a pointer to an EsObject where the return value of the message is placed. argumentCount can be from 0 to 255.

Error cases: Returns an EsPrimErr code.

Side effects: This operation can cause a garbage collection.

Testing objects

These functions enable users to determine what the class and type (immediate, bytes, words, longs, or pointers) of an object are.

EsBehavior EsObjectClass(EsObject object)
Returns the class of object. The generic return type of EsBehavior is used because the class of object can be a Class or Metaclass.

Smalltalk equivalent: object class

BOOLEAN EsIsImmediate(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is immediate.

BOOLEAN EsIsSmallInteger(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is a smallInteger.

BOOLEAN EsIsCharacter(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is a character.

BOOLEAN EsIsNil(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is nil.

BOOLEAN EsIsTrue(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is true.

BOOLEAN EsIsFalse(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is false.

BOOLEAN EsIsBoolean(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is true or false.

BOOLEAN EsIsLargeInteger(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is a largeInteger.

BOOLEAN EsIsFloat(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is a Float.

BOOLEAN EsIsBytes(EsObject object)
Returns TRUE or FALSE, indicating whether or not the instance variables of object contain bytes.

BOOLEAN EsIsWords(EsObject object)
Returns TRUE or FALSE, indicating whether or not the instance variables of object contain words.

BOOLEAN EsIsLongs(EsObject object)
Returns TRUE or FALSE, indicating whether or not the instance variables of object contain longs.

BOOLEAN EsIsPointers(EsObject object)
Returns TRUE or FALSE, indicating whether or not the instance variables of object contain pointers.

BOOLEAN EsIsIndexable(EsObject object)
Returns TRUE or FALSE, indicating whether or not object has numbered instance variables.

BOOLEAN EsIsReadOnly(EsObject object)
Returns TRUE or FALSE, indicating whether or not object is read-only.

BOOLEAN EsIsCharacters(EsObject object)
Returns TRUE or FALSE, indicating whether or not object contains instances of Character. If this returns TRUE, object will be a byte or word object.

Converting Smalltalk objects to C values

These functions enable users to convert Smalltalk objects into C values for processing in a user primitive.

I_32 EsSmallIntegerToI32(EsObject smallInteger)
Returns the signed 32-bit value of smallInteger.

Error cases: smallInteger is assumed to be a smallInteger.

char EsCharacterToChar(EsObject character)
Returns the char value of character.

Error cases: character is assumed to be a character. Some IBM Smalltalk characters will not fit in a char. The return value in this case is unspecified.

U_16 EsCharacterToU16(EsObject character)
Returns the U_16 value of character.

Error cases: character is assumed to be a character.

U_32 EsIntegerToI32(EsObject object, I_32 * value)
Converts object to a C signed 32-bit Integer and stores the result in the location pointed to by value. Returns an EsPrimErr code. If the return value is EsPrimErrNoError then *value is valid. Otherwise, *value is invalid.

Error cases: An error occurs if object is not a smallInteger or largeInteger. An error occurs if the value of the number cannot fit in 32 bits signed.

U_32 EsIntegerToU32(EsObject object, U_32 * value)
Converts object to a C unsigned 32-bit integer and stores the result in the location pointed to by value. Returns an EsPrimErr code. If the return value is EsPrimErrNoError then *value is valid. Otherwise, *value is invalid.

Error cases: An error occurs if object is not a smallInteger or largeInteger. An error occurs if the value of the number cannot fit in 32 bits unsigned.

U_32 EsFloatToCDouble(EsObject object, double * value)
Converts object to a C double and stores the result in the location pointed to by value. Returns an EsPrimErr code. If the return value is EsPrimErrNoError then *value is valid. Otherwise, *value is invalid.

Error cases: An error occurs if object is not a Float.

Converting C values to Smalltalk objects

These functions enable users to convert C values into their corresponding objects for returning to Smalltalk.

EsObject EsI32ToSmallInteger(I_32 value)
Converts value (a signed number) to an IBM Smalltalk smallInteger and returns it.

Error cases: Not all signed 32-bit values can fit in a smallInteger. No range check is done on value. Use EsI32ToInteger or EsU32ToInteger if you are not certain that value fits.

EsObject EsCharToCharacter(char character)
Converts character to an IBM Smalltalk character and returns it.

EsObject EsU16ToCharacter(U_16 value)
Converts value to the corresponding IBM Smalltalk character and returns it.

U_32 EsI32ToInteger(I_32 value, EsObject * object)
Converts value (a signed number) into an integer and stores the result in the location pointed to by object. Returns an EsPrimErr code. If the return value is EsPrimErrNoError then *object is valid. Otherwise, *object is invalid.

Error cases: An error occurs if the new integer object cannot be allocated.

Side effects: This operation can cause a garbage collection.

U_32 EsU32ToInteger(U_32 value, EsObject * object)
Converts value (an unsigned number) into an integer and stores the result in the location pointed to by object. Returns an EsPrimErr code. If the return value is EsPrimErrNoError then *object is valid. Otherwise, *object is invalid.

Error cases: An error occurs if the new integer object cannot be allocated.

Side effects: This operation can cause a garbage collection.

U_32 EsCDoubleToFloat(double value, EsObject * object)
Converts value into a Float and stores the result in the location pointed to by object. Returns an EsPrimErr code. If the return value is EsPrimErrNoError then *object is valid. Otherwise, *object is invalid.

Error cases: An error occurs if the new Float object cannot be allocated.

Side effects: This operation can cause a garbage collection.

Accessing objects

These functions enable users to access the instance variables of an object. For all of the following functions that use an instance variable index, the first instance variable is numbered 1.

U_32 EsInstSize(EsObject object)
Returns the number of named instance variables in object.

Smalltalk equivalent: object class instSize

U_32 EsBasicHash(EsObject object)
Returns the basic hash of the object.

Smalltalk equivalent: object basicHash

U_32 EsBasicSize(EsObject object)
Returns the number of indexed instance variables in object.

Smalltalk equivalent: object basicSize

U_32 * EsInstVarAddr(EsObject object)
Answers the address of the first instance variable of object. The result value is cast to U_32 * regardless of the type of object.

Error cases: Assumes that object consists of not immediate.

EsObject EsInstVarAt(EsObject object, U_32 index)
Returns instance variable index of object. Allows access of named and indexed instance variables; that is, index 1 is the first named instance variable, if object has any.

Error cases: Assumes that object consists of pointers. index is not validated.

Smalltalk equivalent: object instVarAt: index

void EsInstVarAtPut(EsObject object, U_32 index, EsObject storedObject)
Stores storedObject into instance variable index of object. Allows access of named and indexed instance variables; that is, index 1 is the first named instance variable, if object has any.

Error cases: Assumes that object consists of pointers. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object instVarAt: index put: storedObject

EsObject EsAt(EsObject object, U_32 index)
Returns indexed instance variable index of object. Does not allow access of named instance variables.

Error cases: Assumes that object consists of pointers and is indexable. index is not validated.

Smalltalk equivalent: object basicAt: index

void EsAtPut(EsObject object, U_32 index, EsObject storedObject)
Stores storedObject into indexed instance variable index of object. Does not allow access of named instance variables.

Error cases: Assumes that object consists of pointers and is indexable. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object basicAt: index put: storedObject

U_8 EsByteAt(EsObject object, U_32 index), U_8 EsU8At(EsObject object, U_32 index)
Returns the unsigned byte in indexed instance variable index of object.

Error cases: Assumes that object consists of bytes. index is not validated.

Smalltalk equivalent: object basicAt: index

void EsByteAtPut(EsObject object, U_32 index, U_8 value), void EsU8AtPut(EsObject object, U_32 index, U_8 value)
Stores value into indexed instance variable index of object.

Error cases: Assumes that object consists of bytes. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object basicAt: index put: value

U_16 EsWordAt(EsObject object, U_32 index), U_16 EsU16At(EsObject object, U_32 index)
Returns the unsigned word in indexed instance variable index of object.

Error cases: Assumes that object consists of words. index is not validated.

Smalltalk equivalent: object basicAt: index

void EsWordAtPut(EsObject object, U_32 index, U_16 value), void EsU16AtPut(EsObject object, U_32 index, U_16 value)
Stores value into indexed instance variable index of object.

Error cases: Assumes that object consists of words. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object basicAt: index put: value

U_32 EsLongAt(EsObject object, U_32 index), U_32 EsU32At(EsObject object, U_32 index)
Returns the unsigned long in indexed instance variable index of object.

Error cases: Assumes that object consists of longs. index is not validated.

Smalltalk equivalent: object basicAt: index

void EsLongAtPut(EsObject object, U_32 index, U_32 value), void EsU32AtPut(EsObject object, U_32 index, U_32 value)
Stores value into indexed instance variable index of object.

Error cases: Assumes that object consists of longs. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object basicAt: index put: value

I_8 EsSignedByteAt(EsObject object, U_32 index), I_8 EsI8At(EsObject object, U_32 index)
Returns the signed byte in indexed instance variable index of object.

Error cases: Assumes that object consists of bytes. index is not validated.

Smalltalk equivalent: object basicAt: index

void EsSignedByteAtPut(EsObject object, U_32 index, I_8 value), void EsI8AtPut(EsObject object, U_32 index, I_8 value)
Stores value into indexed instance variable index of object.

Error cases: Assumes that object consists of bytes. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object basicAt: index put: value

I_16 EsSignedWordAt(EsObject object, U_32 index), I_16 EsI16At(EsObject object, U_32 index)
Returns the signed word in indexed instance variable index of object.

Error cases: Assumes that object consists of words. index is not validated.

Smalltalk equivalent: object basicAt: index

void EsSignedWordAtPut(EsObject object, U_32 index, U_16 value), void EsI16AtPut(EsObject object, U_32 index, U_16 value)
Stores value into indexed instance variable index of object.

Error cases: Assumes that object consists of words. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object basicAt: index put: value

I_32 EsSignedLongAt(EsObject object, U_32 index), I_32 EsI32At(EsObject object, U_32 index)
Returns the signed long in indexed instance variable index of object.

Error cases: Assumes that object consists of longs. index is not validated.

Smalltalk equivalent: object basicAt: index

void EsSignedLongAtPut(EsObject object, U_32 index, I_32 value), void EsI32AtPut(EsObject object, U_32 index, I_32 value)
Stores value into indexed instance variable index of object.

Error cases: Assumes that object consists of longs. index is not validated. Stores into read-only objects are not checked.

Smalltalk equivalent: object basicAt: index put: value

Protecting objects from garbage collection

Whenever an object is allocated, a garbage collection might be required. If this happens, all non-immediate object pointers stored in user primitive variables are invalidated. If new objects are allocated in user primitives, they must be explicitly protected from garbage collection using the EsSaveObject / EsRestoreObject protocol.

Each object that is referenced only by the user primitive variables must be saved before any operation that could cause a garbage collection. After that operation completes, the objects must be restored in the reverse order from that in which they were saved. All saved objects must be restored before the user primitive succeeds or fails.

void EsSaveObject(EsObject object)
Pushes object onto the Smalltalk stack so that it is protected from a garbage collection.

EsObject EsRestoreObject(void)
Pops the object on the top of the Smalltalk stack and returns it.

Miscellaneous

The virtual machine provides the following miscellaneous functions.

void EsRememberObjectStore(EsVMContext vmContext, EsObject targetObject, EsObject storedObject)
Must be called whenever an object is stored into an instance variable of a pointer object.

For example,

   EsObject myObject;
   EsObject storedObject;
   EsObject * instVar;
   instVar = (EsObject *) EsInstVarAddr(myObject);
   *instVar = storedObject;
   EsRememberObjectStore(EsPrimVMContext, myObject, storedObject);
Note:EsAtPut and EsInstVarAtPut automatically call this function.

U_32 EsVMVersion(void)
Returns the major and minor version numbers of the running virtual machine. To extract the major and minor version numbers from the return value:
   U_32 versionNumber;
   U_16 versionMajor;
   U_16 versionMinor;
 
   versionNumber = EsVMVersion();
   versionMajor = versionNumber >> 16;
   versionMinor = versionNumber & 0xFFFF;

The minor version number should be interpreted as a two-digit decimal number. For example, version 1.21 of the interpreter has minor version 21. Version 1.3 has minor version 30. Both have a major version of 1.

void EsScavenge(EsVMContext vmContext, U_32 bytesRequired)
Causes the scavenger (a part of the garbage collector) to run once.

Smalltalk equivalent: System scavenge

void EsGGC(EsVMContext vmContext, U_32 bytesRequired)
Causes the global garbage collector to run once.

Smalltalk equivalent: System globalGarbageCollect

Classes Available during User Primitives

The following classes (all of type EsBehavior) are available during a user primitive:


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]