Generated Functions

$next$ $up$ $previous$ $contents$ $index$
Next: Predefined Phyla and Operators Up: Output Previous: Generated Data Types

Generated Functions

In this section we describe the various functions that are generated. Every function can be used like any other C function. In the names, the following `meta' notation is used:

phylum is a phylum name (user-defined or predefined), in the list functions phylum corresponds to the list elements.
list is the name of a list phylum.
Operator is an operator name.
result function(); is the definition of a function found in the term processor input.

$\fbox{\sf {\em phylum} {\em Operator}( {\em phylum\_sub1} sub1, ..., {\em phylum\_subn} subn );}$

For each operator a C function is declared, with the same name. This function implements the storage option and returns (a pointer to) the term constructed from its arguments.

$\fbox{\parbox{7cm}{ void *emalloc( kc\_size\_t n ); \\ void *ecalloc( kc\_size\_t n, kc\_size\_t m ); \\ void *erealloc( void *r, kc\_size\_t s ); \\ }}$

The emalloc and friends functions are used for allocating memory, they call the system memory allocation routines and check the return status. The emalloc and friends functions' interfaces use the void* type³, and hide the fact that some malloc libraries use the char* type from the user.

The uniqmalloc and friends routines are used to implement the hashtables' storage. They claim large chunks from the system and pass out small blocks. These blocks cannot be freed by themselves, it is only possible to free a complete collection of chunks as a whole. Each collection of chunks can be identified by its kc_memory_info_t*.

$\fbox{\sf kc\_memory\_info\_t *uniqmallocinit( kc\_size\_t n );}$

Initialize the allocation information of a new set-of-chunks and return a pointer to it.

$\fbox{\sf void *uniqmalloc( kc\_size\_t n, kc\_memory\_info\_t *mi );}$

Returns a pointer to a block of size n from the chunks administrated in mi.

$\fbox{\sf boolean isinuniqmalloccedblock( void *p, kc\_memory\_info\_t *mi );}$

Report whether or not p was allocated via mi.

$\fbox{\sf void uniqfreeall( kc\_memory\_info\_t *mi ); }$

Free all chunks allocated (managed) via mi .

$\fbox{\sf void uniqfreeelement( void *, kc\_memory\_info\_t *mi );}$

Free one block allocated by uniqmalloc. However, its current implementation is a no-op.

In the generated code these allocation routines are used via the following macros: MALLOC and friends are used for all allocation, except for the allocation of memory by the Operator functions. UNIQMALLOC2 is used to allocate memory for the phyla that have the `uniq' storage option. NONUNIQMALLOC is used for the remaining phyla. If you want different ones, redefine MALLOC and friends, in your included code. For example, the default definition of MALLOC and NONUNIQMALLOC is emalloc, the default definition of UNIQMALLOC2 is uniqmalloc.

kc_size_t is by default typedef'ed to unsigned.

The generated code contains the definition of the enumerated type kc_storageclass_t , which contains all storage classes, including the predefined storage class uniq.

$\fbox{\sf kc\_hashtable\_t kc\_ht\_assign( kc\_hashtable\_t ht, kc\_storageclass\_t sc );}$

Makes ht the hashtable for storage class sc, and return the previously assigned hashtable.

$\fbox{\sf kc\_hashtable\_t kc\_ht\_assigned( kc\_storageclass\_t sc );}$

Return the hashtable assigned to storage class sc.

$\fbox{\sf kc\_hashtable\_t kc\_ht\_create\_simple( kc\_size\_t n );}$

Creates a hashtable of size n, using the kc_ht_create_bucketmanagement routine with default allocation routines (uniqmalloc and friends). For the bucket_alloc routines ecalloc and friends are used.

$\fbox{\parbox{10cm}{ kc\_hashtable\_t kc\_ht\_create( \\ \mbox{}\hspace{2cm} kc... ...void *mi), \\ \mbox{}\hspace{2cm} boolean (*in\_block)(void *p, void *mi) ); }}$

Creates a hashtable of size n with the given allocation routines. A 0 argument can be given for uniq_free_all, uniq_free_element and/or for in_block, if those routines are not implemented. This routine uses the kc_ht_create_bucketmanagement routine with default bucket allocation routines (ecalloc and friends).

$\fbox{\parbox{13cm}{ kc\_hashtable\_t kc\_ht\_create\_bucketmanagement( \\ \mbo... ... bucket\_increment, \\ \mbox{}\hspace{2cm} void (*bucket\_info)(void *mi) ); }}$

Creates a hashtable of size n with the given allocation routines. A 0 argument can be given for uniq_free_all, uniq_free_element and/or for in_block, if those routines are not implemented, as well as for the info routines, and either the bucket_free or the bucket_free_all routines.

$\fbox{\sf void kc\_ht\_clear( kc\_hashtable\_t ht);}$

Clears hashtable ht, ie. frees its elements (either using uniq_free_elements or, preferably, uniq_free_all), and its buckets. The result of this routine should be equivalent with calling kc_ht_delete followed by kc_ht_create.

$\fbox{\sf void kc\_ht\_delete( kc\_hashtable\_t ht); }$

First kc_ht_clears the hashtable, and then frees the hashtable itself.

$\fbox{\sf void kc\_ht\_reuse( kc\_hashtable\_t ht);}$

Prepares hashtable ht for reuse, ie. frees its elements, but not its buckets.

$\fbox{\parbox{7cm}{ {\sf casestring mkcasestring( char *s ); \\ nocasestring mknocasestring( char *s ); }}}$

The basic phylum constructors. They convert a value of a C string into the corresponding phylum value. From a casestring or nocasestring value the string can be referenced as cs->name. In the case of case insensitive strings, this field will contain the string as it is capitalized at its first occurrence.

$\fbox{\sf {\em result} {\em function}( {\em args} );}$

The template of user-provided functions.

$\fbox{\sf boolean eq\_{\em phylum}( {\em phylum} p1, {\em phylum} p2 );}$

The function that tests for structural equality of terms. Attribute values do not influence the comparison. If the phylum is uniquely represented, the test always takes constant time. Note that the comparison of a casestring with a nocasestring is not type correct.

$\fbox{\sf void free\_{\em phylum}( {\em phylum} p, boolean recursive);}$

The node p is zeroed and freed. If recursive is True, the subterms are freed as well. The body of a free function for a phylum with storage class uniq is empty.

$\fbox{\sf void freelist\_{\em list}( {\em list} p );}$

Free the list, but not the elements of the list. In other words, free the spine.

$\fbox{\sf {\em list} concat\_{\em list}( {\em list} l1, {\em list} l2);}$

Produce a new list that is the concatenation of the two arguments. If the second argument is the empty list, and the list phylum is not uniquely represented, this is equivalent to a copy of the list nodes (the `spine'). The list elements are never copied.

$\fbox{\sf {\em phylum} copy\_{\em phylum}( {\em phylum} p, boolean copy\_attributes );}$

Return a copy of p. If copy_attributes is False attribute values are initialised as defined in the definition of phylum. If copy_attributes is True the values of the attributes are copied. Please note that this does not imply that the attributes themselves are copied. This function is ineffective on uniquely represented phyla.

$\fbox{\sf {\em list} reverse\_{\em list}( {\em list} l);}$

Produce a list that is the reverse of the argument list.

$\fbox{\sf int length\_{\em list}( {\em list} l);}$

Yield the number of elements in a list, a nil list has zero elements.

$\fbox{\sf {\em phylum} last\_{\em list}( {\em list} l);}$

Yield the last element of a list, or an error if there isn't one.

$\fbox{\sf {\em list} map\_{\em list}( {\em list} l, {\em phylum}(*f)({\em phylum}));}$

Yield the list constructed from the element-wise application of f. It `lifts' f to a function on lists.

$\fbox{\sf {\em list} filter\_{\em list}( {\em list} l, boolean(*f)({\em phylum}));}$

Yield the list of elements of which f is True.

$\fbox{\parbox{8cm}{ {\sf void fprint\_{\em phylum}( FILE *f, {\em phylum} p ); \\ void print\_{\em phylum}( {\em phylum} p ); }}}$

Print the argument term on a given file (f = 0 means standard output - print_phylum( p ) is identical to fprint_phylum( 0, p )) in a canonical format. In this format each operator appears on a separate line. It is mainly intended for debugging.

$\fbox{\parbox{10cm}{ void fprintdot\_{\em phylum}( \\ \mbox{}\hspace{2cm} FILE ... ...\\ void fprintdotprologue( FILE *f ); \\ void fprintdotepilogue( FILE *f ); }}$

Print the argument term p, with its attributes, on a given file (f = 0 means standard output) in dot input format. Dot is a program that draws directed acyclic graphs in various output formats, among which are postscript and gif. It is available as part of the GraphViz graph visualisation package[EKN]. If print_node_labels is True, the nodes are labeled with the names of the operators, the types of the subtrees, and the attribute names and types (or values, for boolean attributes), and the root node is labeled with root_label_prefix followed by phylum. The edges are numbered; the edge numbers show a depth-first left-to-right treewalk. The numbers are prefixed with the contents of edge_label_prefix, which can make it easier to see to which tree an edge belongs when several trees are combined in the same picture, as discussed below. Attributes of the edges (colors, fonts, etc.) can be given with edge_attributes. Shared non-leaf tree nodes appear as such in the drawing. For leaf nodes (like integers, (no)casestrings) the amount of sharing can be influenced with the use_context_when_sharing_leaves argument: if it is False leaf nodes with the same value will be shared (which resembles the internal program structure, but may give pictures that are a bit confusing, especially if no non-leaf nodes are shared), if it is True then the ancestor of the leaf node is taken into account for the sharing, i.e. leaf nodes with the same value but different ancestors will not be shared. Finally, it is possible to combine several trees in one drawing. To do so, start by invoking fprintdotprologue. Next, invoke fprintdot_phylum for each tree, with argument print_prologue_and_epilogue set to False. You likely want to use a different edge_label_prefix for each tree. Finally, invoke fprintdotepilogue. If only one tree is to be drawn, then it is sufficient to invoke fprintdot_phylum with print_prologue_and_epilogue set to True (and fprintdotprologue and fprintdotepilogue need not be invoked 'by hand').

$\fbox{\sf int kc\_set\_fprintdot\_hashtablesize( int s );}$

Set the size of the hashtable that the fprintdot_phylum routines use to detect node-sharing. Return the previous value.

$\fbox{\sf {\em phylum} rewrite\_{\em phylum}( {\em phylum} p, rview v );}$

Yield the normal form of the first argument with respect to the rewrite system and view.

$\fbox{\sf void unparse\_{\em phylum}( {\em phylum} p, void(*kc\_printer)(char *s, uview v), uview kc\_current\_view );}$

Unparses the argument p and its descendants, with view and printer as given.

$\fbox{\parbox{8cm}{ {\sf char *CSGIOread\_{\em phylum}( FILE *f, {\em phylum} *ptr ); \\ char *CSGIOwrite\_{\em phylum}( FILE *f, {\em phylum} p ); }}}$

To read and write a term from a structure file (see Section 3.5). FILE is the standard file i/o type defined in <stdio.h>. The functions return a null pointer if all went well. If not, they return a pointer to a string containing an error message.

$\fbox{\sf int kc\_set\_csgio\_hashtablesize( int s );}$

Set the size of the hashtable that the CSGIOwrite_phylum routines use to detect node-sharing. Return the previous value.

$\fbox{\sf boolean kc\_set\_csgio\_sharing( boolean b );}$

Disable (b = False) or re-enable the use of node-sharing while writing structure files. This does not affect the ability to read structure files that contain node-sharing! By default (if this routine is not called) node-sharing in structure files is enabled. Return the previous value.

$\fbox{\sf void kc\_print\_operator\_statistics( FILE *f );}$

Print for each operator its size in bytes, the number of create calls, the number of actually created elements (usually much lower if its phylum has the uniq storage option), the number of free calls (recursive and non-recursive), the number of freed elements, the number of remaining nodes and the amount of space that these take, in bytes. The routine is equivalent to a no-op, unless the preprocessor symbol KC_STATISTICS is defined.

$\fbox{\sf void kc\_print\_hash\_statistics( FILE *f );}$

Print the number of hashtable buckets that contain zero, one, two, three, four, five, six, seven, eight or more elements.

$\fbox{\sf void kc\_print\_hashtable\_memory\_statistics( FILE *f, kc\_hashtable\_t h );}$

Print information about the memory management of h. (This will only be possible if node- and bucket memory-management routines have been specified.)

$next$ $up$ $previous$ $contents$ $index$
Next: Predefined Phyla and Operators Up: Output Previous: Generated Data Types

2000-04-17