Memory management

DSOM programs must manage four different kinds of memory resources: objects, object references, Environment structures, and blocks of memory. There are different techniques for allocating and releasing each kind of resource.

Objects and object references

Creating and destroying remote objects was discussed previously in this section (see "Creating remote objects" and "Destroying remote objects"). Creating and destroying local objects is described in section 3.2, "Using SOM Classes - the Basics," in Chapter 3, "Using SOM Classes in Client Programs." Object references are typically created automatically by DSOM as needed by the client program. They are also released in the client program by using either the release method or the somdProxyFree method. (The two methods are equivalent.)

Environment structures

When a client invokes a method and the method returns an exception in the Environment structure, it is the client's responsibility to free the exception. This is done by calling either exception_free or somdExceptionFree on the Envirnmen structure in which the exception was returned. (The two functions are equivalent.) A similar function, somExceptionFree, is available for SOM programmers however DSOM programmers can use somdExceptionFree to free all exceptions (regardless of whether they were returned from a local or remote method call).

Blocks of memory

For allocating and releasing blocks of memory within a client program, SOM provides the SOMMalloc and SOMFree functions (analogous to the C "mallo" and "free" functions). The "Memory Management" section of Chapter 3 describes these functions. To release memory allocated by DSOM in response to a remote method call, however, DSOM client programs should use the ORBfree function

For example, when a method is invoked that returns a result of type string, sequence, or array, DSOM will allocate memory for the result in the client's address space. Ownership of this memory becomes the responsibility of the client program. When finished using this memory, the client program should free it using the ORBfree function, rather than free or SOMFree. This is because the memory has been allocated by DSOM using special memory-management techniques; therefore, the client should ask DSOM to also free the memory. If the storage is freed using SOMFree rather than ORBfree, then memory leaks will result.

The differences between the SOMFree and ORBfree functions are twofold:

• First, SOMFree should only be used to free memory not allocated by DSO(for example, memory the client program allocated itself using SOMMalloc), while ORBfree should be used to free memory allocated by DSOM in response to a remote method call.

• Second, SOMFee only frees a single block of memory (in the same way that the C "free" function does), while ORBfree will free an entire data structure, including any allocated blocks of memory within in. For example, if a remote method call returns a sequence of structs, and each struct contains a string, ORBfree will free, with a single call, not only the sequence's "_buffer" member, but also each struct and all the strings within the structs. Freeing a similar data structure using SOMFree would require multiple calls (one for each call to SOMMalloc used to build the data structure).

Some programmers may wish to use a single function to free blocks of memory, regardless of whether they were allocated locally or by DSOM in response to a remote method call. For these programmers, DSOM provides a function, SOMD_NoORBfree, which can be called just after calling SOMD_Init in the client program. (It requires no arguments and returns no value.) This function specifies that the client program will free all memory blocks using SOMFree, rather than ORBfree. In response to this call, DSOM will not keep track of the memory it allocates for the client. Instead, it assumes that the client program will be responsible for walking all data structures returned from remote method calls, while calling SOMFree for each block of memory within.