ESM API Documentation

Version 4.06

Irv.Elshoff@deltares.nl
16 nov 04

Contents


Introduction

ESM can be used for inter-process communication.  In general, one process (or thread) creates a context and communicates it's ID to other processes.  Then processes can allocate and free regions of memory in the context.  When the application is finished, some process should delete the context.

With the exception of ESM_Create, ESM_Alloc and ESM_Error, all ESM functions return a status code indicating success or failure.  ESM_OK (zero) is returned on success; ESM_ERROR (-1) on error.

Contexts

A context is a collection of related memory segments shared by one or more processes on a single host. A host is the domain of a single operating system instance, and may span multiple physical processors.

Contexts are identified by a non-zero integer whose scope is a host (for shared memory) or address space (for local memory).  Positive context IDs are for shared memory contexts, negative IDs for local memory.  An application program can use both kinds of contexts simultaneously.

Shared memory contexts have user/group permissions that are enforced by UNIX. All processes must have the same effective user and group ID to share a context (this may be relaxed in the future).

Each process (including all threads in that process) can be connected to ESM_MAX_CON (presently 64) contexts simulataneously.

Pages

Shared memory contexts are made up of one or more pages.    UNIX SVR4's shared memory facility limits the number of memory segments (pages) that may be allocated and attached to a process (less than 100 in most cases). Choosing an appropriate page size is important (see ESM_Create).

Regions

A region is a named block of memory with a context.  Regions cannot be larger than a page in shared memory contexts (local memory contexts do not have this constraint).

Function Specifications

ESM_Init

int status = ESM_Init (
    int flags
    );
This function initializes ESM, and must be called by each process or thread before using the other ESM functions.  It sets process/thread specific flags (logically or-ed):
Returns ESM_OK when ESM is ready, or ESM_ERROR if an error occurred.

ESM_Create

int contextID = ESM_Create (
    int shared,
    int pagesize
    );
This function creates a new context for regions.  If shared is non-zero, the context will be created in UNIX SVR4 shared memory; otherwise it will be in local memory.

In the shared case, a positive page size (in kilobytes) must be specified.   A too small page size will eventually exhaust the maximum number of attached pages.  A too large page size could waste memory.  10 MB is probably a good value for most programs, but a larger value (e.g., 100 MB) may be needed for memory-intensive programs.

Shared memory is not presently implemented on Microsoft Windows.

ESM_Create returns a context ID, or zero if an error occurred and the context could not be created.

ESM_Delete

int status = ESM_Delete (
    int contextID
    );
This function deletes a context and frees all memory associated with it.  Regions in the context (i.e., pointers previously returned by ESM_Alloc) should not be used by any process afterwards.  It is the programmer's responsibility to ensure that this cannot happen.  ESM has no way of knowing if a process is still using memory in a context.

Returns ESM_OK if successful, and ESM_ERROR if an error occurred (e.g., the context does not exist).

ESM_Alloc

void * pointer = ESM_Alloc (
    int contextID,
    char * name,
    int size
    );
If the size argument is positive, this function reserves a region of (shared) memory in the specified context, maps it into the virtual addess space of the calling process, and returns the local address of the first byte in the region.  NULL is returned if an error occurred (e.g., resources exhausted).  The name is assigned to the region for subsequent lookups (by other processes).

If the size if not positive, the name is looked up and the pointer to the region returned if previously allocated, or NULL is the region is unknown.  No memory is allocated.

A region with a particular name and size may exist at most once in a context.  In other words, it is OK to allocate a region X of size Y more than once (subsequent allocations return the existing pointer), but attempting to allocate region X with size Z will fail and return NULL if size Y != Z already exists.

ESM_Free

int status = ESM_Free (
    int contextID,
    char * name
    );
This functions frees the space associated with the named region and return 0 upon success and -1 otherwise.  The (pointer to the) region should not be used subsequently by any process or thread.  Doing so may result in unpredictable results or a program crash.   Returns ESM_OK or ESM_ERROR.

ESM_ListContexts

int status = ESM_ListContexts (
    FILE * outputfile
    );
This functions prints a human-readable list of contexts known to a process.  Contexts are known after they are created or when a region was allocated or freed in the context.  Output is written to the file descriptor, which must be opened for writing.  Returns ESM_OK or ESM_ERROR.

ESM_ListRegions

int status = ESM_ListRegions (
    int contextID,
    FILE * outputfile
    );
This functions prints a human-readable list of all regions in the specified context.  Output is written to the file descriptor, which must be opened for writing.  Returns ESM_OK or ESM_ERROR.

ESM_Error

char * errormessage = ESM_Error (
    void
    );
Returns a pointer to a character string describing the reason for the last ESM function failure.

ESM_TraceFile

int status = ESM_TraceFile (
    char * filename
    );
If the ESM_TRACE flag is set during initialization, a trace of every operation is written to standard output.  The ESM_TraceFile function can be used to specify an alternative file.  Each thread that uses ESM can have its own trace file.  Returns ESM_OK upon success or ESM_ERROR if the file could not be created or appended to.