A chain represents a container where there is a two-way ordering (predecessor and successor) imposed on the stored objects. Objects may be added and removed at either end or anywhere in the middle of the chain. Objects may also be indexed by a signed, zero-based integral type, ‘ssize_t’. A chain is a ‘struct chain’ (with a ‘typedef’ name of ‘Chain’) whose members are private.
User data is not stored directly in an object of type ‘Chain’, but in an intermediate type called a ‘Chainlink’. These objects are not allocated explicitly by the user. The procedure for retrieving data from a chain is to call a function on the chain which returns a chainlink, and then to call a function on the chainlink which yields the stored data. User data is stored as generic pointers (‘void *’).
Given a ‘Chainlink *’, the user can use the following function to retrieve the data stored in that chainlink:
Returns the user-supplied pointer stored in the chainlink node.
All the ‘Chain’ and ‘Chainlink’ functions are declared in libretto/chain.h.