Initializing a Shared Arena

Initializing a Shared Arena

All IRIX IPC mechanisms require a shared memory arena. A program creates a shared memory arena with the usinit() function. However, many attributes of the arenas that usinit() creates are set by preceding calls to usconfig().

Configuring an Arena

You often call usconfig() prior to creating an arena in order to establish the following features:

CONF_INITSIZE Set the initial size of the arena segment. The default is 64 KB, and often you know that more is needed immediately.
CONF_INITUSERS Set the largest number of concurrent processes that can use the arena. The default is 8; if the program creates more child processes than this, the limit must be set higher.
CONF_CHMOD Set effective file permissions on arena access. The default is 600, allowing only processes with the effective UID of the creating process to attach the arena.
CONF_ARENATYPE Set optional arena handling choices.
CONF_LOCKTYPE Set lock metering on for locks created in this arena.

See the usconfig(3P) reference page for a complete list of attributes. In programs that start a varying number of child processes, it is a common mistake to find that the eighth child cannot be created simply because usconfig() has not been used to set a higher number of users before an arena was created.

Creating an Arena

Having set the arena attributes, the program calls usinit(), specifying a file pathname string.

Tip: The mktemp() library function can be used to create a unique temporary filename (see the mktemp(3C) reference page). If the specified file doesn't exist, usinit() creates it. If a shared arena already exists based on that name, usinit() joins that shared arena. If the file exists but isn't a shared arena, usinit() overwrites it. In any case, usinit() is subject to normal filesystem permission checks: it returns an error if the process doesn't have read and write permission on the file (if it already exists) or permission to create the file (if it doesn't exist).

Code to prepare an arena is shown in Example 2-1.

Example 2-1 : Initializing a Shared Memory Arena

usptr_t 
makeArena(size_t initSize, int nProcs)
{
   int ret;
   char * tmpname = "/var/tmp/arenaXXXXXX";
   if (ret = usconfig(CONF_INITUSERS, nProcs))
   { perror("usconfig(#users)"); return 0; }
   if (ret = usconfig(CONF_INITSIZE, initSize))
   { perror("usconfig(size)"); return 0; }
   return usinit(mktemp(tmpname));
}

Joining an Arena

Only one process creates a shared arena--other processes "join" or "attach" the arena. There are three ways of doing this. Normally, the arena is not restricted to a single process family. In this case, any process that calls usinit() and passes the same pathname string gains access to the same arena at the same virtual base address. This process need not be related in any way to the process that created the arena.

You can restrict arena access to a single process and to the children it creates with sproc() by calling usconfig() to set the arena type before creating the arena. When this is done, a call to usinit() with the same pathname creates a new arena at a possibly different base address. The two arenas are related through the contents of the file, and unpredictable results can occur if the processes do not coordinate updates to the data.

An arena is a segment in the address space of a process. When that process creates a new process using sproc(), the child process usually shares the same address space (see the sproc(2) reference page). The child process has access to the arena segment on the same basis as the parent process. However, the child process needs to join the arena formally.

The child process should join the arena by calling usadd(), passing the address of the arena. The child should test the return code of this function, since it can reflect an error in either of two cases:

The arena has not been created, or an incorrect arena address was passed.
The arena was not configured to allow enough using processes, and no more users can be allowed.

A child process can join an arena automatically, simply by using a semaphore, lock, or barrier that is allocated within that arena. These function calls perform an automatic call to usadd(). However, they can also encounter the error that too many processes are already using the arena. It is best for the child process to check for this condition with an explicit call to usadd().

CONF_INITSIZE	Set the initial size of the arena segment. The default is 64 KB, and often you know that more is needed immediately.
CONF_INITUSERS	Set the largest number of concurrent processes that can use the arena. The default is 8; if the program creates more child processes than this, the limit must be set higher.
CONF_CHMOD	Set effective file permissions on arena access. The default is 600, allowing only processes with the effective UID of the creating process to attach the arena.
CONF_ARENATYPE	Set optional arena handling choices.
CONF_LOCKTYPE	Set lock metering on for locks created in this arena.