cache_ctx

NAME: cache_ctx - standard cache abstraction

SYNOPSIS

#include <cache_ctx.h>

typedef struct cache_state_ {
    char          *key;
    a2c_module    *module;
    UINT4          selector;
} *cache_state;

int CACHE_delete(ctxp)
  cache_ctx    *ctxp;

int CACHE_get(ctx, state, data, heap)
  cache_ctx      ctx;       /* IN */
  cache_state    state;     /* IN */
  VOID          *data;      /* OUT */
  alloc_ctx      heap;      /* IN */


int CACHE_put(ctx, state, data)
  cache_ctx      ctx;       /* IN */
  cache_state    state;     /* IN */
  VOID          *data;      /* IN, may be 0 */

int CACHE_getany(ctx, state, data, heap)
  cache_ctx      ctx;       /* IN */
  cache_state    state;     /* IN */
  asn__any      *data;      /* OUT */
  alloc_ctx      heap;      /* IN */

int CACHE_putany(ctx, state, data)
  cache_ctx      ctx;       /* IN */
  cache_state    state;     /* IN */
  asn__any      *data;      /* IN, may be 0 */

DESCRIPTION

cache_ctx is a cache abstraction that allows SETREF to maintain state through the course of a SET transaction.

CACHE_delete() deletes the cache_ctx. A cache_ctx is no longer usable following a call to CACHE_delete().

CACHE_get() obtains data from the cache, placing the data into a C-native data structure.

CACHE_put() places data into the cache, obtaining the data from a C-native data structure.

CACHE_getany() obtains data from the cache, placing the data, in DER-encoded form, into an asn__any. See ASN.1/DER runtime types for additional information.

CACHE_putany() places data into the cache, obtaining it, in DER-encoded form, from an asn__any. See ASN.1/DER runtime types for additional information.

PARAMETERS: Both CACHE_put() and CACHE_putany() can take a 0 pointer for the data parameter. In this case, the state is cleared from the cache. Subsequent calls to either CACHE_get() or CACHE_getany() requesting that state will return CACHE_CTX_WARN_NO_STATE.

RETURN VALUES

On success, CACHE_delete() returns NO_ERROR. On failure, CACHE_delete() returns CACHE_CTX_ERR_BAD_PARAMETER.

When the requested state is not in the cache, CACHE_get() and CACHE_getany() return CACHE_CTX_WARN_NO_STATE

See Return Values for descriptions of individual error codes. For documentation on displaying or logging return values, see error_ctx.

SEE ALSO: cache_ctx_db

NOTES: The ctx argument must be initialized prior to use. See cache_ctx_cb for information on creating a cache_ctx.
CACHE_get(), CACHE_put(), CACHE_getany(), CACHE_putany(), and CACHE_delete() are macros, but only the ctx argument appears more than once in the macro expansion. Therefore, it is safe to use arguments with side effects (in particular, those using the ++ or -- operator), for all arguments except ctx. These macros should always be used to invoke the underlying functions, rather than invoking the functions directly.

EXAMPLE

int
add_XID_to_cache(xid)
    asn1set__XID   *xid;
{
    cache_ctx       msg_cache;       /* per-transaction data */
    char           *name;            /* cache name */


    /*  Open the per-transaction cache.  
     *
     *  In this example, the transaction ID (XID) is used to 
     *  identify the appropriate cache. */

    name = xid2name(xid);

    status = create_cache_ctx_db(&msg_cache, name);
    assert(status == NO_ERROR);


    /*  Insert the XID into the cache.
     *
     *  If 'xid' was passed in as an asn__any,
     *  CACHE_putany() would be used instead. */

    status = CACHE_put(msg_cache, STATE_XID, xid);
    assert(status == NO_ERROR);


    /*  Delete the cache object.  If other messages associated
     *  with this transaction are going to be processed, the
     *  cache could remain open.
     *
     *  In this case, CACHE_delete does not delete the underlying
     *  cache (which is the semantics of cache_ctx_db, a cache_ctx
     *  that uses a database for persistence). */

    status = CACHE_delete(&msg_cache)
    assert(status == NO_ERROR);

    return NO_ERROR;
}

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.