rtm_alloc() is part of a high-performance memory management system that the BeOS genki/6 Media Kit provides.

rtm_alloc() is primarily used in critical portions of the Media Kit. Media node writers can also take advantage of rtm_alloc() in the time-sensitive portions of their code.

To answer this, it's important to understand how malloc works. malloc first tries to reserve memory in RAM to give you what you need. If there isn't enough room in RAM, the kernel's virtual memory system takes over. The kernel then swaps out pages of memory from RAM to your hard drive to make room for your request. In addition, memory created by malloc can be swapped to disk to make room for other memory that needs to be used. For most applications, the overhead incurred by malloc and virtual memory is negligible compared to other performance factors that affect your code, and the advantages offered by virtual memory far outweigh the cost.

For media nodes that must run in real time, however, malloc is not good enough. Why? Because the virtual memory management system costs you time, not only from pushing blocks of memory around, but also from switching between your thread and the kernel. And if this isn't heinous enough, there's always the chance that your memory will be swapped out to disk later on, resulting in possible additional overhead whenever you try to access the memory. For time-sensitive media nodes, this overhead can be crippling, causing audio glitches or other undesirable performance artifacts.

rtm_alloc() is a mechanism which bypasses virtual memory and its vices. As memory management systems go, rtm_alloc() is almost painfully simple. You use it by creating a pool of memory ahead of time. rtm_alloc() then assigns chunks of memory from this pool. In this case, allocating and freeing memory are trivial operations on already extant memory. So, as long the pool has enough available memory to deliver to you, no trip to the kernel is necessary. In addition, the media real-time allocator will lock this pool of memory into RAM, meaning that the memory cannot be paged out by the virtual memory engine. In short, allocating and freeing memory doesn't trigger VM, and the memory you get will stick around in RAM, so there's no VM overhead there.

The power of rtm_alloc() is also its major drawback. Because you're creating and locking a pool of memory for your application to use, that memory is completely dedicated to your application—which means that the effective amount of RAM available for other applications is reduced, and their performance will suffer. Another potential problem you might run into is memory fragmentation, as rtm_alloc() does almost nothing to deal with this issue. For these reasons, we recommend that you only use rtm_alloc() when you absolutely need it.

Although memory is cheap, we realize that not everybody may want to devote a significant chunk of their RAM exclusively to media applications at the expense of the rest of their system. For this reason, the media real-time allocator will only lock its memory pools into RAM if either Real-Time Audio or Real-Time Video is enabled. These two options are set by the user by check boxes in the Media Preferences panel.

Here's how it basically works. See the header file RealtimeAlloc.h in the Media Kit for more details.

First, use rtm_create_pool to create the memory pool you wish to use. Because this creates an area, which involves the VM system, you should do this before the real-time madness starts. You give it the size of the pool and the name (which should be B_OS_NAME_LENGTH bytes or less). You get back an opaque pointer, rtm_pool*, that uniquely identifies your pool.

Keep in mind that, when creating pools, you should try to specify the minimum amount of memory that you'll need. Also note that there is some overhead for every pool that you create, and the number of pools you can have is limited, so it's better to create one pool for your purposes rather than several smaller ones.

Another important note about pools: there is always one pool available for use called the "default pool." This is the pool used by the Media Kit for its own real-time allocation needs. I will forego subtlety and say: don't use the default pool! Create your own pool instead, so that you don't starve the Media Kit and associated classes.

rtm_pool* my_pool;
status_t err = rtm_create_pool(&my_pool, 0x1000,
  "My Real-Time Pool");
if (err != B_OK) {
  // there's probably no RAM left for you to lock down:
  // the system is seriously stressed!
  ...
}

Now, once you have a pool, use rtm_alloc() to get the memory you need. You identify the pool and the amount of memory to reserve. If this pool doesn't have enough memory left, not all is lost! rtm_alloc() will try to "grow" the pool by creating a new area big enough to hold the memory, before failing. (Doing this could potentially involve VM, though, so this will cost you.)

size_t size = ...;
void* ptr = rtm_alloc(my_pool, size);
if (! ptr) {
  // Bad news, Buck: we're out of memory!
  ...
}

Once you're done with the memory, simply free it by using rtm_free():

status_t err = rtm_free(ptr);
if (err != B_OK) {
  // ptr was probably NULL
  ...
}

As soon as you're done using the memory pool, be sure to delete it, so that the system can reclaim your RAM for others to use.

status_t err = rtm_delete_pool(my_pool);
if (err != B_OK) {
  // my pool was probably already deleted
  ...
}

For an example of the real-time allocator in action, and how you can redefine the C++ operators new and delete to use real-time allocation, check out the sample code:

<ftp://ftp.be.com/pub/samples/media kit/rtm_test.zip>

This provides a couple of super-simple tests you can run on either regularly allocated objects or rtm_alloc()'ed objects. Hopefully, this code will demonstrate just how significant the performance savings can be, though of course, your actual mileage will vary.

Because rtm_alloc() memory locking is controlled by the "Enable Real-Time Audio/Video" check boxes in the Media Preferences panel, this facility is not really appropriate for non-media applications. Any application can, however, create a pool of memory that is locked into RAM by using areas:

size_t size = ...;

// round up to a multiple of the page size
// this works because B_PAGE_SIZE is a power of 2
size = (size + B_PAGE_SIZE - 1) & ~(B_PAGE_SIZE - 1);
void* my_pool;

 area_id area = create_area("My Pool", &my_pool,
  B_ANY_ADDRESS, size, B_FULL_LOCK,
  B_READ_AREA | B_WRITE_AREA);

 if (area < 0) {
  // some error occurred
  ...
}

Doing memory allocation from this pool (perhaps as a C++ allocator template?) is left as an exercise for the reader.