Package Overview
Riverbed programs use two mechanisms to gracefully handle low-memory conditions:
- Memory reserves
- A low-memory notification mechanism
The primary mechanism for ensuring robustness in the face of low-memory conditions is the use of one or more memory reserves. A memory reserve is created at application startup and is held by the application until all attempts to allocate memory fail. In this event, the reserve is released back to the OS in an attempt to satisfy the pending memory allocation request. The released memory is used also to perform tasks such as triggering clean-up functions and alerting the user of the low-memory condition.
The other mechanism is the use of callbacks to notify client modules of a low-memory condition (that is, the failure of a memory allocation). At startup, client modules register callbacks that are called during low-memory conditions. These callbacks free memory in an attempt to allow the application to continue, notify the user of the low-memory condition, and can perform other tasks such as disabling memory-intensive operations. The memory manager attempts to fulfill the failed allocation request following the clean-up process.
The low-memory callbacks are prioritized by how extensive their clean-up tasks are. There are three priority levels:
- Garbage—The most basic callbacks simply free non-essential data that is maintained in memory, such as output reports and unused state information.
- Performance—Callbacks with this priority are called if the Garbage-level cleanup is not sufficient to satisfy a pending memory request. These callbacks can take more drastic measures, such as disabling or removing a module’s object caches (at the cost of performance). In addition, a built-in Performance-level callback notifies the user of the low-memory condition by sending a warning message to the console, logging the warning in the error log, and displaying the Low-Memory Warning dialog box.
- Emergency—In case of an emergency, a module might choose to do a destructive clean-up such as destroying the Undo stack.
Riverbed programs call the low-memory callbacks in priority order. Thus, the Garbage-level callbacks are called first. If they fail to release enough memory to satisfy pending memory requests, the Performance-level callbacks are called. Finally, if necessary, the Emergency-level callbacks are called.
Using Osys_Lowmem_Callback_Register(), you can register custom callbacks to perform clean-up activities that are specific to your code. Your custom callbacks can be assigned to any of the three priority levels and will be called after the built-in low-memory callbacks of the corresponding level.
If your code uses the memory management API to allocate memory (see Chapter 5 "Memory and Pooled Memory Package" on page 54), the built-in and any custom low-memory callbacks will be triggered automatically when needed. If your code does not use the memory management API (for example, if it uses the C language malloc() function directly), you must trigger the low-memory callbacks yourself using Osys_Lowmem_Callbacks_Trigger().