Real-Time Allocation Functions

Declared in: be/media/RealtimeAlloc.h

Library: libmedia.so

　media nodeは、時間というものに対して高度に敏感な存在です。作業の動作にわずかな遅れが生じただけで、メディアの再生や録音の品質に激烈な問題を生じる原因になるかも知れません。普段はユーザにとって大きな利益となる仮想メモリは、メディア処理をする際には処理の妨げになり得ます。時間の厳密さに欠ける仮想メモリの領域にヒットすることは、メディア演奏を中断する原因になる可能性があります。

　リアルタイムなメモリ割り当てとロック機能は、仮想記憶システムがnodeのメモリをディスクにキャッシュしてしまうことを防ぐため、nodeをロックダウンする方法を提供します。これはnodeが自分自身や使用しているメモリがスワップファイルから取り出される間停止しなければならないという事態を回避します。

　ユーザはどのようなタイプのnodeがロックされたメモリを使用するか、Media performanceアプリケーションを用いて設定することができます。典型的には、nodeはmalloc()及びfree()の代りに、リアルタイムなメモリ割り当てを使用すべきです。rtm_alloc()はB_MEDIA_REALTIME_ALLOCATORフラグがセットされれば自動的にメモリのロックを扱うので、あなたのnodeはそのことについて思い悩む必要はありません。

Memory Pools

　リアルタイムなメモリブロックは、poolに領域確保されます。poolは、リアルタイムアロケータがBMediaRoster内でオンにされた場合、物理RAMにロックされます。poolがメモリにロックされている間、他のアプリケーションによって使用できる物理RAMの量が減少します。従って、リアルタイムブロックがあなたの処理に対して実際に有益にならない場合、それを使用してはいけません。

　poolを生成する際、poolのサイズの合計を指定します。このサイズは、poolから領域確保できる最大のバイト数です。メモリは、rtm_alloc()の呼び出しによってpoolに領域確保することができ、メモリブロックはrtm_free()の呼び出しによって解放することができます。

The Default Pool

　デフォルト（または共有）のpoolと呼ばれる、特別なpoolが存在します。望めばこのpoolにメモリブロックを領域確保することができますが、これは少ないリソースであり、一般的な規則としてそれを回避することはできません。

　その代わりに、あなた自身のpoolを生成し、使用して下さい。デフォルトのpoolは、本来の目的のためにmedia node及びMedia Kitに使用させて下さい。

MALLOC_DEBUG

　rtm_alloc()は、MALLOC_DEBUGの値に応答します。もし環境変数MALLOC_DEBUGが0以外に設定されていれば、new或いはfreeされたブロックは、なんらかのゴミの値でクリアされます。もしそれに1以上の整数が設定されていれば、pool、ヒープ及びブロックの確認が適切な時に行われるでしょう。それは完璧な確認ではありませんが、何もしないよりはよいことです。

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()は、指定されたpoolにsizeバイトのメモリブロックを領域確保します。もしpoolにNULLを指定した場合、メモリはデフォルトのpoolに領域確保されます。

　rtm_realloc()は、dataによって参照されるブロックのサイズをnewSizeバイトの長さに変更します。バッファは新しいサイズにaccomodateするために移動する必要があるかも知れません。そのため、dateによって参照されていたポインタは変更になる可能性があります。もしdataがNULLであれば、これはデフォルトのpoolでrtm_alloc()を呼び出すのとちょうど同じになります。

RETURN CODES

• B_OK. エラーなし。

• B_BAD_VALUE. dataポインタがNULLである。

• B_NO_MEMORY. poolが満杯である。

rtm_create_pool() , rtm_delete_pool()

	status_t rtm_create_pool(rtm_pool **outPool, size_t totalSize,       const char *name = NULL) status_t rtm_delete_pool(rtm_pool *pool)

　rtm_create_pool()は、新しいメモリのpoolを生成します。poolのrtm_pool参照は、outPoolに保存されます。poolは、totalSizeのデータを維持するに足る容量を持ち、指定されたnameを与えられます。

　もしoutPoolがNULLならば、デフォルトのpoolが存在していない場合にはそれが生成されます。これが実行された場合、EALREADYが返されます。

　rtm_delete_pool()は、指定されたpoolを削除します。デフォルトのpoolは削除できません。poolにNULLを渡すと、B_BAD_VALUEが返されるでしょう。

一度poolを使用し終えたら、必ずそれを削除して下さい。

RETURN CODES

• B_OK. エラーなし。

• EALREADY. デフォルトのpoolがすでに存在している（rtm_create_pool()のみ）。

• B_BAD_VALUE. デフォルトのpoolは削除できない。

• エリアエラー.

rtm_default_pool()

	rtm_pool *rtm_default_pool(void)

　デフォルトのpoolのポインタを返すか、或いはもしそれが初期化されていなければNULLを返します。

rtm_delete_pool() see rtm_create_pool()

rtm_free()

	status_t rtm_free(void *data)

　指定されたデータブロックを解放します。

RETURN CODES

• B_OK. エラーなし。

• B_BAD_VALUE. NULLポインタが与えられた。

rtm_phys_size_for() see rtm_size_for()

rtm_realloc() see rtm_alloc()

rtm_size_for() , rtm_phys_size_for()

	status_t rtm_size_for(void *data) status_t rtm_phys_size_for(void *data)

　rtm_size_for()は、指定されたメモリブロックのサイズを返します。

　rtm_phys_size_for()は、指定されたメモリブロックの物理的なサイズを返します。これは、実際にブロックを移動させるという危険なrtm_realloc()を使用せずにブロックが拡大できる最大のバイト数です。

RETURN CODES

• B_OK. エラーなし。

• B_BAD_VALUE. dataポインタがNULLである。