---

4.3.2.8 struct x1f4_nodetype_type

typedef struct x1f4_nodetype_type {
    const char *name;
    int (*call)(struct x1f4_nodelink_type *), code,
	(*copy)(void *, void *, void **, const void *,
		const struct x1f4_nodelink_type *),
	(*dump)(void *, struct x1f4_nodelink_type *),
	(*free)(void *, void *, struct x1f4_nodelink_type **,
		const struct x1f4_nodelink_type *),
	(*hash)(void *, struct x1f4_nodelink_type **,
		struct x1f4_nodelink_type *),
	(*lead)(void *, void **),
	(*miss)(struct x1f4_nodelink_type **, struct x1f4_nodelink_type **,
		struct x1f4_nodelink_type *),
	(*move)(void *, void *, const struct x1f4_nodelink_type *,
		const struct x1f4_nodelink_type *),
	(*node)(void *, void **, void *, const struct x1f4_nodelink_type *),
	(*pick)(void *, void *, struct x1f4_nodelink_type **,
		const struct x1f4_nodelink_type *),
	(*post)(void *, void **, const struct x1f4_nodelink_type *),
	(*pull)(void *, void *, void *, const void *,
		struct x1f4_trans_type *, struct x1f4_caselink_type **),
	(*push)(void *, void **, void *, const struct x1f4_nodelink_type *),
	(*slip)(void *, void **);
    unsigned flags, size;
    void *context;
} x1f4_nodetype_type;

The x1f4_nodetype_type record describes data types. It details such (application and programming language) data type attributes as name and id, and data operations such as copying and freeing. It details reference management operations as well.

See Referable Objects.

name

The name field is the type name, i.e. the string that introduces declarations of variable of this application defined type.

size

The size field is the type name length, i.e. the number of characters (not including the terminal null) making up the type name.

code

The code field is the type id, i.e. the number that will identify run time data as belonging to this type.

See Intrinsic Types.

See Application Defined Types.

flags

The flags is a bitwise OR of zero or more common data type flag bits.

See Common Data Type Flags.

context

The context field is the context of this very type definition. It is passed as argument to type specific methods and not used otherwise.

call

The call field indicates the routine marking an object as being in the process of destruction.

The method is used only for data types for which objects may be referred more than once and can store references to other objects (class 3).

See Object Classes.

The method is used in the first stage of cycle dismantling.

See Cycle Dismantling.

When called, the call routine is supplied the address of the struct x1f4_nodelink_type field of the object to be processed as its sole argument.

See struct x1f4_nodelink_type.

The method is expected to return zero, the return is not used.

copy

The copy field indicates the routine copying data and setting it as (being) referred by some described object.

More specifically, the copy method copies one object. The newly made copy will be referred exactly once (and thus, if the data type defines a reference count that count will need to be set as 1).

The newly made copy will be referred by an object, and not by a variable. If the data type defines a list of objects holding references to data the object referring the newly made copy will need be recorded with the list.

See Object and References.

The copy field may be set to NULL, case in which routines copying data in accordance with the struct x1f4_nodetype_type record will simply copy the pointer to where data is stored.

When the copy field is not NULL, the free field is assumed indicating a valid routine. If free is indicating a valid routine, other than a trivial, no operation one, copy will likely point some non trivial routine doing the opposite (if the free decrements some reference counter, copy will likely increment it).

While the intended use of the copy routine is copy-creating new objects, where not possible or desirable copy may merely register a new object reference, just the way the node routine does. Such is the case for objects that are not meant to be copied (like opened files), but that allow multiple linking.

When called, the copy routine is supplied the data type specific context (the context field in this very record), the reference tracking context, the address where to store the address of the newly made data copy, the address of the object to be copied and the struct x1f4_nodelink_type description of the object making reference to the newly made data copy as arguments, in this order.

See struct x1f4_nodelink_type.

Copying objects making references to other objects poses supplementary challenges. References are to be tracked, data referred more than once needs to be copied only once. The second method argument indicates the reference tracking context. If no reference tracking context is defined for the operation, NULL may be passed instead.

See Data Replication.

See Non Recursive Data Replication.

The method is expected to return zero for success, non zero for failure.

dump

The dump field indicates the routine destroying an object.

The method is used only for data types for which objects may be referred more than once and can store references to other objects (class 3).

See Object Classes.

The method is used in the third (last) stage of cycle dismantling.

See Cycle Dismantling.

When called, the dump routine is supplied the data type specific context (the context field in this very record) and the address of the struct x1f4_nodelink_type field of the object to be destroyed as arguments, in this order.

See struct x1f4_nodelink_type.

The method is expected to return zero for success, non zero for failure.

free

The free field indicates the routine removing a reference to data (object O) hold by a described object (P) and freeing data when it is no longer referred.

If the data type defines a reference count, the reference count is to be decremented for O.

If the data type stores the list of objects making references to data, the object holding the reference (P) needs to be removed from the list.

See Object Classes.

If references are no longer being made to data, the data (O) needs be freed.

If references are still being made to data yet data belongs to a reference cycle, data needs be freed as well.

See Detecting Cycles.

The free field may be set to NULL, not so if the copy field is not NULL itself.

Non NULL lead and slip fields also imply a non NULL free. So is the X1f4_LX_LINK_ACCESS bit, that allows the node field to be used.

When dismantling cycles (in the libaime referable objects type system), the reference count may be set to 0 before the free method is called. The method will test the count for 0 value and upon positive result will return without further processing.

See Cycle Dismantling.

If O is to be destroyed (for the reference count reached 0) the references hold by O to other objects need be removed as well. In turn, the reference count for these objects may reach 0 and they will need to be destroyed. Such procedure should be as simple as calling the appropriate free methods for the objects to which O holds references.

For the same cycle dismantling purposes the objects to which O holds references may need to be added to the list of objects making the scope of the cycle dismantling routine - even if the object (O) for which the free method has been called will be freed immediately.

When called, the free routine is supplied the data type specific context (the context field in this very record), the address of O, the struct x1f4_nodelink_type cycle dismantling list of objects and the struct x1f4_nodelink_type description of P as arguments, in this order.

See struct x1f4_nodelink_type.

If no struct x1f4_nodelink_type cycle dismantling list of objects is defined when calling free, NULL is to be passed for the third argument - if one is defined, it is to be passed instead.

If the struct x1f4_nodelink_type cycle dismantling list of objects (the third argument) is not NULL, the objects for which the destruction was triggered (by the destruction of the object making the subject of the free method call) are to be added to the list.

The method is expected to return zero for success, non zero for failure.

hash

The hash field indicates the routine removing the references held by a specified object.

The method is used only for data types for which objects may be referred more than once and can store references to other objects (class 3).

See Object Classes.

The method is used in the second (mid) stage of cycle dismantling.

See Cycle Dismantling.

When called, the hash routine is supplied the data type specific context (the context field in this very record), the address where a struct x1f4_nodelink_type pointer is stored and the address of the struct x1f4_nodelink_type field of the object to be processed as arguments, in this order.

The second argument is the address at which the head of the list of the objects being destroyed is stored. If more objects are to be added to the list by the method, the (objects are to be added to the head of the list and the) new head of the list is to be stored at the address indicated by the same third argument. The list is a linked list in which the slip field of some struct x1f4_nodelink_type record indicated the next item, some other struct x1f4_nodelink_type record.

See struct x1f4_nodelink_type.

The method is expected to return zero for success, non zero for failure.

lead

The lead field indicates the routine acknowledging the addition of a variable held reference.

Same as the struct x1f4_datatype_type lead method.

See struct x1f4_datatype_type.

miss

The miss field indicates the routine determining whether an object is part of a set of objects referring one each other and being not referred from outside the set. In effect, the routine is the proper cycle detector.

When called, the miss routine is supplied two struct x1f4_nodelink_type pointer addresses and the address of the struct x1f4_nodelink_type record from which the miss method was picked up (it is expected that the address of the object embedding this struct x1f4_nodelink_type record may be derived from this last argument) as arguments, in this order.

The first struct x1f4_nodelink_type pointer address (the routine first argument) indicates the list to which the examined objects are to be added. The second struct x1f4_nodelink_type pointer address (and the routine second argument) indicates the list to which the to be examined objects are to be added.

Adding the objects holding references to the one being examined to the second list (that of the to be examined objects) is an alternative to the possibly recursive examination of these objects.

The method is expected to return zero if the object is part of a set of objects referring one each other and being not referred from outside the set, non zero otherwise.

How the miss method is expected to derive its result from its input is detailed in the cycle detection algorithm description.

See Detecting Cycles.

See Reference Tracking Mechanics.

The method is used only for data types for which objects may be referred more than once and can store references to other objects (class 3).

See Object Classes.

move

The move field indicates the routine transferring the reference to data hold by a described object to another described object.

If the data type defines a reference count, the reference count needs not be modified.

If the data type defines a list of objects holding references to data type data the object holding the reference to be transferred needs to be removed from this list and the object to which the reference is transferred needs be added to the list.

Cycles of references of objects otherwise not referred may form. The newly formed cycles are to be detected and dismantled.

See Detecting Cycles.

The move field may be set to NULL.

When called, the move routine is supplied the data type specific context (the context field in this very record), the address at which the object for which the reference is to be transferred is stored, the struct x1f4_nodelink_type description of the object holding the reference to be transferred and the struct x1f4_nodelink_type description of the object to which the reference is to be transferred to, as arguments, in this order.

See struct x1f4_nodelink_type.

The method is expected to return zero for success, non zero for failure.

node

The node field indicates the routine registering an object held reference.

If the data type defines a reference count, the reference count is to be incremented. If the data type defines a list of objects holding references to data the object holding the reference is to be added to the list.

The address of the data is to be copied at some specified location.

The node field value is used only when the flags field includes the X1f4_LX_LINK_ACCESS bit.

See Common Data Type Flags.

When the node field is to be used, the free field is assumed indicating a valid routine.

When called, the node routine is supplied the data type specific context (the context field), the location at which the data address is to be copied, the data address (the object for which a new reference is being created) and the struct x1f4_nodelink_type description of the object holding the new reference as arguments, in this order.

See struct x1f4_nodelink_type.

The method is expected to return zero for success, non zero for failure.

pick

The pick field indicates an alternate routine removing a data reference hold by a described object (from the tracked references list) and freeing data when no longer referred.

Unlike the primary free reference removal routine, pick is expected non recursive. Instead of freeing objects, the routine is expected to add them to the list indicated by its third parameter.

Also unlike free, pick does always expect a cycle dismantling list of objects (and a non NULL third argument).

Just like free, pick is to check for cycles if data is still being referred. If cycles are detected, the routine should add the entire cycle to the list of objects to be free.

See Detecting Cycles.

For the objects belonging with the libaime referable objects type system, the reference count (of the objects added to the to be freed list) should be set to 0.

pick retains the remaining free semantics.

The pick field value is used only when the flags field includes the X1f4_LX_PICK_ACCESS bit.

post

The post field indicates the routine constructing new data and setting it as (being) referred by a described object.

More specifically, the post method sets up one object. The new object will be referred exactly once (and thus, if the data type defines a reference count that count will need to be set as 1). The same new object will be referred by some other object, and not by a variable. If the data type defines a list of objects holding references to data type data the object referring the new object will need be recorded with that list.

See Object and References.

The post field value is used only when the flags field includes at least one of the X1f4_LX_POST_ACCESS and X1f4_LX_PULL_ACCESS bits.

See Non Recursive Data Replication.

When called, the post routine is supplied the data type specific context (the context field in this very record), the address at which the address at which the new object is stored is to be stored and the struct x1f4_nodelink_type description of the object making reference to the new object as arguments, in this order.

See struct x1f4_nodelink_type.

The method is expected to return zero for success, non zero for failure.

pull

The pull field indicates the routine setting up newly created object copies to match the copied objects. The routine is used in the second step of non recursive data replication.

See Non Recursive Data Replication.

The pull field value is used only when the flags field includes the X1f4_LX_PULL_ACCESS bit.

When called, the pull routine is supplied the data type specific context (the context field in this very record), the reference tracking context, the address of the object being set up, the address of the reference object, a memory manager in the struct x1f4_trans_type definition and the address where the head of the struct x1f4_caselink_type items list of objects created and yet to be set up is stored as arguments, in this order.

See struct x1f4_trans_type.

See struct x1f4_caselink_type.

Copying objects making references to other objects poses supplementary challenges. References are to be tracked, data referred more than once needs to be copied only once. The third method argument indicates the reference tracking context.

See Data Replication.

If in the process of setting up the newly made object copy (to match the object being copied) new objects are created and they are to be set up later (presumably by a call of a similar pull method) they are to be added to the struct x1f4_caselink_type linked list of objects still to be processed. The head of the list is stored at the address indicated by the method last argument and is to be updated accordingly. If new items are added to the list they are to be allocated as prescribed by the struct x1f4_trans_type argument of the method.

The method is expected to return zero for success, non zero for failure.

push

The push field indicates the routine transferring the reference to data (object O) hold by a described object (P) to a variable (V, of the same aime type as O) and in the process removing the reference hold by the variable (V) to whatever object (R) it refers, and possibly freeing the object (R).

If the data type defines a reference count, the reference count needs not be modified for O.

If the data type defines a list of objects holding references to data, the object holding the reference (P) needs to be removed from the list.

The object R previously referred by V has to dereferenced, much like for the free method, only now no object holding reference to data needs be removed from any list.

Specifically, if the data type defines a reference count, the reference count for R needs decremented. If no references are still being made to R, the object needs freed. If references are still being made, it may be that the object belongs to a reference cycle (objects referring one each other and being referred by no variable and no object outside cycle) and R still needs freed.

See Detecting Cycles.

If the data type does not allow multiple references, R needs to be destroyed.

The method should safely detach O from P, even when the latter is the variable referred object (R).

See Temporaries.

The destruction of R should be delayed until after the current expression evaluation is completed, as a temporary reference to the object may have been taken (the method should arrange for a later destruction of R instead of immediately destroying the object).

See Delayed Disposal.

The method should allow for uninitialized variables, and thus for no variable referred objects. No object needs to be dereferenced for uninitialized variables. The variables will store a data type specific value indicating the not yet initialized state (like NULL), value set by the preinitializing method of the data type.

See struct x1f4_datatype_type.

Non NULL lead and slip fields require a non NULL push.

push field may be otherwise set to NULL, with the effect of disallowing reference transfers from objects to variables. Non NULL copy and free fields should nonetheless see a non NULL push, as otherwise objects may be lost while transferring references to variables.

The push indicated method may get used to remove object held references without transferring the removed references to any variable. Such uses would not pose further requirements on the push method implementation. They would see the objects P and R being the same and they would serve to delay the destruction of P.

The address of O is expected to be copied at the address where the variable value is stored.

When called, the push routine is supplied the data type specific context (the context field in this very record), the address where the variable value (initially the address of R) is stored, the address of O and the struct x1f4_nodelink_type description of O as arguments, in this order.

See struct x1f4_nodelink_type.

The method is expected to return zero for success, non zero for failure.

slip

The slip field indicates the routine acknowledging the removal of a variable held reference.

Same as the struct x1f4_datatype_type slip method.

See struct x1f4_datatype_type.

See Referable String Data Type.

See Intrinsic Integer Data Type.