Fusion:Arena

An arena is an inter-process repository for storing pointers to shared memory. You store the pointers in fields within the arena. Arenas and fields are uniquely identified by names of your choosing (field names must only be unique within the arena).

To gain access to an arena you call fusion_arena_enter with a string specifying which arena you’re interested in. If the arena doesn’t exist it will be created, otherwise its reference counter will just be incremented. When you’re done using an arena, call fusion_arena_exit to decrement its reference counter, and destroy it if the reference count goes to zero.

When entering an arena you pass in pointers to your own initialize and join functions, one of which will be called back from fusion_arena_enter. The initialize function is called if the arena didn’t previously exist, and is your opportunity to allocate one or more chunks of shared memory and store pointers to them as fields in the arena with a call to fusion_arena_add_shared_field. The join function is your opportunity to use fusion_arena_get_shared_field to retrieve the pointers.

Retrieved pointers are typically saved in process-local variables so they can be used directly without having to go through the arena each time. That means that you’ll only really use the arena once per process during initialization. However, you need to postpone exiting the arena until your process shuts down so that the arena isn’t destroyed before other processes get around to entering it.

There is no check to ensure that you don’t add two fields with the same name. If you do, the last one added will be the one retrieved the other(s) will still take up a little space in shared memory but will be inaccessible until the arena is destroyed.

Since there’s no shared memory in the single-app configuration, there’s no need for arenas either. Stub functions are implemented, but they just return FUSION_SUCCESS without doing anything. You better follow the above advice and only use the arena from within your initialize callback and keep your pointers in your own variables.