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.

This document was generated on November 8, 2012 using texi2html 1.82.