Refcount Handling

 

The information about references to an instance is stored in the instance itself -- this is what the instance variable refcount of the base class Root is used for. If no reference to an instance exists (that is the instance is only used once), the refcount is zero, for each reference created it is incremented and for every reference deleted it is decremented. As explained above an instance can only be deleted if there are no references left. For checking if there are references "delete" uses the method

   GRAPE(inst, "zero-refs")()

INSTANCE * inst

This method must return NULL if there are still references left and a different value (usually inst) if the instance inst can be deleted. Root "delete" calls "zero-refs", if it returns NULL only the refcount is decremented otherwise "free" is called.

For most classes you don't have to write a "zero-refs" method, because Root "zero-refs" (which just checks the refcount and returns the appropriate value) can be used, only for classes with cyclic references like TimeStep or Geom2d a special "zero-refs" method is needed.

Deleting references must be handled by the "delete" method, to simplify creating references the macro

ASSIGN(<ref>, <inst>)

is provided. Here both <ref> and <inst> are pointers to an instance struct, the macro will copy the pointer <inst> to <ref> and increment the refcount of the instance.

Never try to copy an instance by copying the C structure (of course this can be used to copy datatypes which are structs like COMPLEX). This will get you into big trouble, because it destroys the instance list of the class the instance belongs to. To copy instances the copy methods described in section 5.4.5.1 can be used.