NAME
arena_create - Initialise the arena with the specified ID and prepare it for use.
SYNOPSYS
#include <charm.h>
#include <syserror.h>
#include <ArenaData.h>
Status arena_create ( int arena_id, Cap auth);
PARAMETERS
arena_id Specifies the identity of the Arena to be initialised.
auth Specifies the management capability for the specified Arena.
DESCRIPTION
The arena_create() function is used to initialise the meta-data associated with a particular Arena such that the Arena may be used. The arena_id parameter specifies the identity of the Arena to be initialised. It is an index into the ArenaData array that is maintained by the kernel (see get_kernel_data()). The size of this array is specified as the kernel constant num_arenas. The auth parameter specifies a capability that is used to prevent unauthorised initialisation of the Arena.
Before creating an arena, it is advisable to examine the corresponding ArenaData structure to ensure that the arena is marked as free. Once this is established, the auth capability of the arena should be set to a private value (see arena_change_caps()). This provides a form of mutual exclusion on the arena, thereby allowing an arena_create() call to be made without race conditions.
Following a successful call to arena_create(), the specified arena is marked as used in the corresponding ArenaData structure.
RETURN VALUES
Upon the successful completion, the arena_create() function returns [SUCCESS] to show that the arena has been created without any errors. Otherwise, arena_create() returns an error status.
ERRORS
[NO_SUCH_ARENA] The arena_id parameter is not valid (out of range).
[ARENA_CAP_INVALID] The auth parameter specifies a capability that does not match the current authorisation capability associated with the arena.
[ARENA_NOT_FREE] The specified arena is not marked as free in the corresponding ArenaData structure.
RELATED INFORMATION