Real-Time Allocation Functions

Declared in: be/media/RealtimeAlloc.h

Library: libmedia.so

Media nodes are highly timing-sensitive creatures. The slightest delay in performing their work can cause drastic problems in media playback or recording quality. Virtual memory, normally of great benefit to users, can work against them when doing media work. A poorly-timed virtual memory hit can cause breaks in media performances.

The realtime memory allocation and locking functions provide a means for nodes to lock down their memory to prevent it from being cached to disk by the virtual memory system. This avoids situations in which the node has to pause while it or its memory is fetched back from the swap file.

The user can use the Media preference application to configure what types of nodes should use locked memory. Nodes should typically use the realtime memory allocation functions instead of malloc() and free(). rtm_alloc() will automatically handle locking the memory if the B_MEDIA_REALTIME_ALLOCATOR flag is set, so your node doesn't have to worry about it.

Memory Pools

Real-time memory blocks are allocated in pools. Pools are locked into physical RAM if realtime allocators are turned on in the BMediaRoster. While pools are locked in memory, that reduces the amount of physical RAM available to other applications, so don't use real-time blocks unless it's really going to benefit your performance.

When you create a pool, you specify the total size of the pool. This size is the maximum number of bytes that can be allocated from the pool. Memory can then be allocated out of the pool by calling rtm_alloc(), and memory blocks in the pool can be freed by calling rtm_free().

The Default Pool

There's a special pool, called the default (or shared) pool. You can allocate memory blocks in this pool if you wish, but it's a scarce resource and as a general rule you should avoid it.

Instead, you should create your own pool and use that; let the media nodes and Media Kit use the default pool for its own purposes.

MALLOC_DEBUG

rtm_alloc() responds to the value of MALLOC_DEBUG. If the MALLOC_DEBUG environment variable is set to anything other than 0, new and freed blocks will be cleared to some junk value. If it's set to an integer greater than 1 it will also do pool, heap, and block validations at opportune times. It's not perfect validation, but it's better than nothing.

Global C Functions

rtm_alloc() , rtm_realloc()

	void *rtm_alloc(rtm_pool *pool, size_t size) status_t *rtm_realloc(void **data, size_t newSize)

rtm_alloc() allocates a block of memory of size bytes in the specified pool. If you specify NULL for pool, the memory is allocated in the default pool.

rtm_realloc() resizes the block referenced by data to be newSize bytes long. Since the buffer may have to move to accomodate the new size, the pointer pointed to by data may change. If data is NULL, this is just like calling rtm_alloc() on the default pool.

RETURN CODES

• B_OK. No error.

• B_BAD_VALUE. The data pointer is NULL.

• B_NO_MEMORY. The pool is full.