Previous: struct x1f4_nodelink_type, Up: Application Interface Types
typedef struct x1f4_nodetype_type {
const char *name;
int code, (*copy) (void *, void *, void **, const void *,
const struct x1f4_nodelink_type *),
(*free) (void *, void *, void *, const struct x1f4_nodelink_type *),
(*move) (void *, void *, void *, const struct x1f4_nodelink_type *,
const struct x1f4_nodelink_type *),
(*node) (void *, void *, void **, void *,
const struct x1f4_nodelink_type *),
(*post) (void *, void *, void **, const struct x1f4_nodelink_type *),
(*push) (void *, void *, void **, void *,
const struct x1f4_nodelink_type *);
unsigned flags, size;
void *context;
} x1f4_nodetype_type;
The x1f4_nodetype_type record describes some data type for certain
libx1f4i0 interfaces operating data of such type. 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.
namename field is the type name, i.e. the string that introduces
declarations of variable of this application defined type.
sizesize field is the type name length, i.e. the number of characters
(not including the terminal null) making up the type name.
codecode field is the type id, i.e. the number that will identify run
time data as belonging to this type.
See Intrinsic Types.
flagsflags is a bitwise OR of zero or more common data type flag bits.
contextcontext field is the context of this very type definition. It is
passed as argument to type specific methods and not used otherwise.
copycopy field is the address of 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 same newly made copy
will be referred by some other object, that is to say, it will not be pointed
to by some variable. If the data type defines a list of objects holding
references to data type data the object referring the newly made copy will need
be recorded with that list.
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.
When called, the copy routine is supplied the execution context, the
data type specific context (the context field in this very record), the
address at which the address at which the newly made data copy is stored is to
be stored, 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.
The method is expected to return zero for success, non zero for failure.
freefree field is the address of the routine removing some data
reference hold by some described object from the tracked references list and
when the reference count becomes zero freeing data.
If the data type defines a reference count, the reference count is to be decremented. If the data type defines a list of objects holding references to data type data the object holding the reference to be removed needs to be removed as well from such list.
If no references are being made to data, the data needs be freed.
If references are still being made to data yet data belongs to some reference cycle (objects of which cycle are referring one each other and being referred by no variable and no object outside 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.
When called, the free routine is supplied the execution context, the
data type specific context (the context field in this very record), the
address at which the object to be freed is stored and the struct
x1f4_nodelink_type description of the object holding the reference to be
removed as arguments, in this order.
See struct x1f4_nodelink_type.
The method is expected to return zero for success, non zero for failure.
movemove field is the address of the routine transferring the reference
to data hold by some described object to some other 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 to be transferred to needs be added to the list.
Cycles of references of objects otherwise not referred may form. In such eventuality the data must be freed.
See Detecting Cycles.
The move field may be set to NULL.
When called, the move routine is supplied the execution context, 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.
nodenode field is the address of the routine registering some data
reference to be hold by some described object.
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 type data the object to hold the reference is to be added to the list.
The address at which the data is stored is expected to be copied to some specified location.
The node field value is used only when the flags field in this
very record include the X1f4_LX_LINK_ACCESS bit and when used is
expected to point some valid routine.
When called, the node routine is supplied the execution context, the
data type specific context (the context field in this very record), the
address at which the address at which the data is stored is to be copied, the
address of the object to be referenced and the struct x1f4_nodelink_type
description of the object to hold 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.
postpost field is the address of the routine constructing new data and
setting it as (being) referred by some 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, that is to say, it will not be pointed to by
some 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.
The post field value is used only when the flags field in this
very record include the X1f4_LX_POST_ACCESS bit and when used is
expected to point some valid routine.
When called, the post routine is supplied the execution context, 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.
pushpush field is the address of the routine transferring the reference
to data hold by some described object to some variable and in the process
removing the reference hold by the same variable to whatever object it refers,
from that object, and possibly freeing that same object.
If the data type defines a reference count, the reference count needs not be modified for the object for which the reference is transferred.
If the data type defines a list of objects holding references to data type data the object holding the reference to be transferred (to the object for which the reference is transferred) needs to be removed from the such list of objects holding references to the object for which the reference is transferred.
The object previously referred by the variable 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 the object referred by the variable needs decremented. If no references are still being made to the same variable referred object, the object needs freed. If references are still being made, it may be that the object belongs to some reference cycle (objects of which cycle are referring one each other and being referred by no variable and no object outside cycle) the object needs freed as well.
See Detecting Cycles.
The push field may be set to NULL.
The address at which the data for which the reference is to be transfered is stored is expected to be copied at the address at which the address at which the variable referred object was stored.
When called, the push routine is supplied the execution context, the
data type specific context (the context field in this very record), the
address at which the address at which the variable referred object is stored
and at which first address the address at which data is stored is to be stored,
the address at which the object for which the reference is to be transferred is
stored and the struct x1f4_nodelink_type description of the object
holding the reference to be transferred, as arguments, in this order.
See struct x1f4_nodelink_type.
The method is expected to return zero for success, non zero for failure.