8.1.1 The class OZ_Extension

The class OZ_Extension implements the methods defined below. The methods getIdV, gCollectV, and sCloneV which are marked as required are pure virtual and have to be implemented in every subclass.

virtual int getIdV() // required

Allows to discriminate the different kinds of extensions. It should return a unique number. Unique numbers can be obtained using int OZ_getUniqueId().

Ids can be statically assigned by extending the enumeration OZ_Registered_Extension_Id.

virtual OZ_Extension* gCollectV() // required

Needed for garbage collection.

virtual OZ_Extension* sCloneV() // required

Needed for cloning of computation spaces (for OZ_SituatedExtension).

virtual void gCollectRecurseV() // required

Invoked on the copy obtained from gCollectV. The VM has marked the data such that recursive updates of fields, e.g. running OZ_gCollect, does not run into cycles.

virtual void sCloneRecurseV() // required

Invoked on the copy obtained from sCloneV. The VM has marked the data such that recursive updates of fields, e.g. running OZ_sClone, does not run into cycles.

virtual OZ_Term printV(int depth = 10) // default: return extension

printV should return a virtual string and is used for printing, e.g. System.show.

virtual OZ_Term printLongV(int depth = 10, int offset = 0) // default: call printV

This may help debugging, but is currently not used.

virtual OZ_Term typeV() // default: return extension

typeV should return an atom describing the type of the extension. This value is also return in Value.status and Value.type. It should not conflict with the built-in types.

virtual OZ_Term inspectV() // default: call typeV

Not used. Idea: hook for debugging tools to get information.

virtual Oz_Boolean isChunkV() // default: return true

Define this to return false is the extension in not a subtype of chunk.

virtual OZ_Term getFeatureV(OZ_Term fea) // default: return 0

If the operator . (dot) is applied to an extension this function is called. If getFeatureV returns 0 an exception is raised that the feature is not available.

virtual OZ_Return getFeatureV(OZ_Term,OZ_Term&) // default: return OZ_FAILED

The is the more basic version of the above, where a reference to the return value is passed as the 2nd argument.

virtual OZ_Return putFeatureV(OZ_Term,OZ_Term) // default: return OZ_FAILED

Feature is 1st argument, new value is 2nd argument. This is used e. g. for := support.

virtual OZ_Return eqV(OZ_Term t) // default: return false

This function is called during unification and equality test (==), if both values are extensions. Implement it if you need structural equality. Note that in this case isChunkV should return false.

virtual OZ_Boolean toBePickledV() // default: return false

return true if pickling is defined.

virtual OZ_Boolean pickleV(MarshalerBuffer *) // default: return false

This is the hook to pickling. It is only called when toBePickledV returned true, and must return true by itself. It writes the extension's external representation into the given buffer (see oz_registerExtension below).

virtual OZ_Boolean marshalSuspV(OZ_Term te, ByteBuffer *, GenTraverser *) // default: return false

This is the hook to serialization for Oz distribution. It returns true if the extension has been serialized, and writes its external representation/a fragment of into the given buffer (see oz_registerExtension below). It returns false if the extension cannot be serialized.

virtual int minNeededSpace() // default: return 0

This method is used by the Oz distribution's serialization routine. It must return the minimal possible size of the next fragment of the extension's external representation. This number must be consistent with the marshalSuspV method described above.

OZ_Boolean isLocal()

Returns true if a situated extensions is local to the current space.