Lists of Pairs of Ports - avram - a virtual machine code interpreter

Next: Ports and Packets, Previous: Emulation Primitives, Up: Emulation Primitives

3.8.1 Lists of Pairs of Ports

A port is the name given to a type of pointer used in the library as the address of a place where a computational result yet to be evaluated will be sent. Ports are discussed further in Ports and Packets, but are mentioned here because it is sometimes necessary to employ a list of pairs of them. A pointer to such a list is declared as a portal type. It refers to a structure of the form

     struct port_pair
     {
       port left;
       port right;
       portal alters;
     }

A small selection of functions for portal memory management is declared as follows in the header file portals.h. For reasons of C-ness, the type declarations themselves are forced to be in lists.h.

— Function: portal avm_new_portal (portal alters)

This function is used to create storage for a new port_pair structure, and returns a portal pointer to it if successful. If the storage can't be allocated, a NULL pointer is returned. The alters field of the result is initialized as the given parameter supplied by the caller. All other fields are filled with zeros.

— Function: void avm_seal (portal fate)

This function performs the reclamation of storage associated with portal pointers, either by freeing them or by consigning them temporarily to a local cache for performance reasons. Client programs should use only this function for disposing of portal storage rather than using free directly, so as to allow accurate record keeping.

— Function: void avm_initialize_portals ()

This function should be called by a client program prior to calling either of the above memory management functions in order to initialize some local variables. Anomalous results are possible otherwise.

— Function: void avm_count_portals ()

This function should be called at the end of a run or after the last call to any of the other functions in this section as a way of detecting memory leaks associated with portal pointers. A warning message will be written to standard error if any remains unreclaimed.