4.6 Other functions available to modules

In addition to the functions above, the VMProxy that is made available to modules contains entry-points for many functions that aid in developing GNU Smalltalk extensions in C. This node documents these functions and the macros that are defined by `gstpub.h'.

Function: void asyncSignal (OOP)

This functions accepts an OOP for a Semaphore object and signals that object so that one of the processes waiting on that semaphore is waken up. Since a Smalltalk call-in is not an atomic operation, the correct way to signal a semaphore is not to send the signal method to the object but, rather, to use:

asyncSignal(semaphoreOOP)

The signal request will be processed as soon as the next message send is executed.

Caution: This is the only function in the intepreterProxy that can be called from within a signal handler.

Function: void syncWait (OOP)

This functions accepts an OOP for a Semaphore object and puts the current process to sleep, unless the semaphore has excess signals on it. Since a Smalltalk call-in is not an atomic operation, the correct way to signal a semaphore is not to send the wait method to the object but, rather, to use:

asyncWait(semaphoreOOP)

The sync in the name of this function distinguishes it from asyncSignal, in that it cannot be called from within a signal handler.

Function: OOP objectAlloc (OOP, int)

The objectAlloc function allocates an OOP for a newly created instance of the class whose OOP is passed as the first parameter; if that parameter is not a class the results are undefined (for now, read as "the program will most likely core dump", but that could change in a future version).

The second parameter is used only if the class is an indexable one, otherwise it is discarded: it contains the number of indexed instance variables in the object that is going to be created. Simple uses of objectAlloc include:

OOP myClassOOP; OOP myNewObject; myNewObjectData obj; ... myNewObject = objectAlloc(myClassOOP); incAddOOP(myNewObject); obj = (myNewObjectData) oopToObj(myNewObject); obj->arguments = objectAlloc(classNameToOOP("Array"), 10); incAddOOP(obj->arguments); ...

The macros are:

Macro: mst_Object oopToObj (OOP)

Dereference a pointer to an OOP into a pointer to the actual object data (see section 4.7 Manipulating instances of your own Smalltalk classes from C). The result of oopToObj is not valid anymore if a garbage-collection happens; for this reason, you should assume that a pointer to object data is not valid after doing a call-in, calling objectAlloc, and caling any of the "C to Smalltalk" functions (see section 4.4 Manipulating Smalltalk data from C).

Macro: mst_Boolean oopIsReadOnly (OOP)

Answer whether or not the given OOP is read-only (see section 3.5 Special kinds of object). Note that being read-only only limits access to indexed instance variables from Smalltalk code. Fixed instance variables, usage of instVarAt:put: and C accesses cannot be write-protected.

Macro: makeOOPReadOnly (OOP, mst_Boolean)

Set whether or not the given OOP is read-only.

Macro: markOOPToFinalize (OOP, mst_Boolean)

Set whether or not the given OOP is a `finalizable' oop. (see section 3.5 Special kinds of object).

Macro: makeOOPWeak (OOP, mst_Boolean)

Set whether or not the given OOP is a `weak' oop (see section 3.5 Special kinds of object).

Macro: OOP oopClass (OOP)

Return the OOP for the class of the given object. For example, oopClass(stringToOOP("Wonderful GNU Smalltalk")) is the String class, as returned by classNameToOOP("String").

Macro: mst_Boolean isClass (OOP, OOP)

Return whether the class of the OOP passed as the first parameter is the OOP passed as the second parameter.

Macro: mst_Boolean isInt (OOP)

Return a Boolean indicating whether or not the OOP is an Integer object; the value of Integer objects is encoded directly in the OOP, not separately in a mst_Object structure. It is not safe to use oopToObj and oopClass if isInt returns false.

Macro: mst_Boolean isOOP (OOP)

Return a Boolean indicating whether or not the OOP is a `real' object (and not an Integer). It is safe to use oopToObj and oopClass only if isOOP returns true.

Macro: mst_Boolean isNil (OOP)

Return a Boolean indicating whether or not the OOP points to nil, the undefined object.

Macro: mst_Boolean arrayOOPAt (mst_Object, int)

Access the character given in the second parameter of the given Array object. Note that this is necessary because of the way mst_Object is defined, which prevents indexedOOP from working.

Macro: mst_Boolean stringOOPAt (mst_Object, int)

Access the character given in the second parameter of the given String or ByteArray object. Note that this is necessary because of the way mst_Object is defined, which prevents indexedByte from working.

Macro: mst_Boolean indexedWord (some-object-type, int)

Access the given indexed instance variable in a variableWordSubclass. The first parameter must be a structure declared as described in 4.7 Manipulating instances of your own Smalltalk classes from C).

Macro: mst_Boolean indexedByte (some-object-type, int)

Access the given indexed instance variable in a variableByteSubclass. The first parameter must be a structure declared as described in 4.7 Manipulating instances of your own Smalltalk classes from C).

Macro: mst_Boolean indexedOOP (some-object-type, int)

Access the given indexed instance variable in a variableSubclass. The first parameter must be a structure declared as described in 4.7 Manipulating instances of your own Smalltalk classes from C).