3.4 Freeing a Persistent Memory Block

This section describes the API calls used for freeing persistent memory blocks.

3.4.1 Responsibility

A persistent memory block can remain in memory beyond the lifetime of a run-time instance of the actor which allocates the block. This immediately raises the question of responsibility for freeing blocks of persistent memory. When a traditional ChorusOS 4.0 user actor terminates, any memory regions it allocated (using rgnAllocate(2K)) are automatically freed. Clearly, this simple rule makes little sense in the case of persistent memory blocks, which can survive beyond such a termination.

The hot restart feature provides two solutions to this problem:

• Actors can explicitly free blocks of persistent memory using the API function pmmFree() or pmmFreeAll(). This is the only solution available for non-restartable actors which use persistent memory: for these actors, freeing persistent memory is entirely the programmer's responsibility.

  If persistent memory needs to survive beyond the persistent lifetime of the allocating actor (that is, even after the actor has cleanly terminated), implementing this solution will require either careful application design or the presence of a garbage collection actor.

  Explicit freeing of persistent memory blocks is described in the next section.

• Hot restartable actors can benefit from an automatic clean-up mechanism provided by the Hot Restart Controller. This is described in more detail in "4.2.3 Freeing Persistent Memory".

In both cases, freeing a persistent memory block has the same effect: the block is immediately and permanently freed (cannot be retrieved), and the name which identified it can be re-used to identify a different memory block.

3.4.2 Freeing a Persistent Memory Block Explicitly

Use the pmmFree() or pmmFreeAll() function to explicitly free a persistent memory block. The explicit freeing of a given memory block can be performed by any actor, not necessarily the actor which originally allocated the block. It is the programmer's responsibility to ensure that the persistent memory block which will be freed is no longer in use.

Use pmmFree() to free a single memory block identified by a PmmName:

#include <chPmm.h>
int pmmFree( PmmName	*name )

Use pmmFreeAll() to free a group of persistent memory blocks which were allocated with the same deletion key. The deletion key for a persistent memory block is specified when the block is allocated with pmmAllocate().

#include <chPmm.h> 
int pmmFreeAll( PmmDelKey    delkey,
                size_t       delKeySize );

A typical use of a deletion key is to mark all persistent memory blocks used by an actor or a group of actors with the same key, and then have a separate, independent actor that frees all the blocks when a particular job is completed or a particular event occurs. For example, the "hello world" example uses pmmFree() to free the single memory block it allocates before it terminates. If the "hello world" actor did not free its own persistent memory block, the following call to pmmFreeAll() from another actor would free the block, along with any other blocks marked with the deletion key HR_GROUP.

pmmFreeAll( HR_GROUP, sizeof(HR_GROUP) );