[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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