core.memory

memory モジュールは、ガベージコレクタおよび、その他のOSやAPIレベルのメモリ管理機能へのインターフェイスを提供します。

Source:
core/memory.d

License:
Boost License 1.0

Authors:
Sean Kelly

struct GC;

この構造体は、 D言語のガベージコレクタの全ての機能をカプセル化しています。

static void enable();

disable() によって一時停止されていた場合に、ガベージコレクタの自動動作を再度有効にします。この関数は再入可能で、 disable 一回につき対応する enable を一回ずつ呼び出す必要があります。

static void disable();

実行のフットプリントを最小にするために、ガベージコレクタの自動動作を停止します。メモリ不足時など、ガベージコレクタによる回収動作がプログラムの正常動作に不可欠な場合は、 disable 状態でもガベージコレクタが動くことがあります。この関数は再入可能ですが、各 disable に対応して enable を一回ずつ呼び出す必要があります。

static void collect();

完全なメモリ回収を行います。この関数の意味はガベージコレクタの実装によって異なりますが、典型的な動作としては、スタックセグメント全体をルートとしてアクセス可能な全てのメモリブロックを alive としてマークし、到達されなかったメモリを回収するというものになります。この操作の際は、実行中の全てのスレッドが停止されることがあります。

static void minimize();

管理するメモリ領域を最小化し、使われていない物理メモリをOSに返すよう指示します。実際にOSに返却されるメモリ量はアロケータの実装やプログラムの挙動に依存します。

enum BlkAttr;

メモリブロックの属性を表すビットフィールドの要素。 getAttr, setAttr, clrAttr 関数で使用します。

FINALIZE: このブロック内のデータは回収時にfinalizeが行われる
NO_SCAN: このブロックは回収時にスキャンされない
NO_MOVE: このブロックが回収時に移動されることはない
APPENDABLE: このブロックは領域拡大を可能にする情報を含んでいます

alias BlkInfo;

管理されたメモリブロックに関する情報を含む構造体です。詳細な情報が必要な場合に、より効率的なクエリをサポートするために使用されます。

base = 対象のブロックのベースアドレスへのポインタ。 size = baseから始まるブロックのサイズ。 attr = メモリブロックの属性ビット。

static uint getAttr(in void* p);

p の参照するメモリに設定される全てのブロック属性を表現するビットフィールドを返します。p がこのGCでアロケートされたメモリを指していない場合、あるいはメモリブロックの途中を指している場合、または p が null の場合は、ゼロを返します。

Params:

void* p

有効なメモリブロックのルートへのポインタ、または null

Returns:
p の参照するメモリブロックの属性ビット。エラー時はゼロ。

static uint setAttr(in void* p, uint a);

p の参照するメモリに、指定された属性ビットをセットします。 p がこのGCでアロケートされたメモリを指していない場合、あるいはメモリブロックの途中を指している場合、または p が null の場合は、何も起きません。

Params:

void* p	有効なメモリブロックのルートへのポインタ、または null
uint a	このメモリブロックに設定したいビットフィールド。

Returns:
実行後 getAttr を呼び出すと返されるようになる値

static uint clrAttr(in void* p, uint a);

p の参照するメモリから、指定された属性ビットをクリアします。 p がこのGCでアロケートされたメモリを指していない場合、あるいはメモリブロックの途中を指している場合、または p が null の場合は、何も起きません。

Params:

void* p	有効なメモリブロックのルートへのポインタ、または null
uint a	このメモリブロックからクリアしたいビットフィールド。

Returns:
実行後 getAttr を呼び出すと返されるようになる値

static void* malloc(size_t sz, uint ba = 0);

ガベージコレクタの管理するメモリに、alignされたブロックを要求します。このメモリはfreeを呼び出して明示的にdeleteすることも、コレクタの実行によって自動的に回収することも可能です。割り当てが失敗した場合、onOutOfMemory 関数を呼び出し、そこで通常は OutOfMemoryException 例外が投げられます。

Params:

size_t sz	割り当てたいバイト数
uint ba	このブロックにセットするビットマスク

Returns:
割り当てられたメモリへの参照。十分なメモリが無かった場合は null を返します。

Throws:
割り当て失敗時に OutOfMemoryException

static void* calloc(size_t sz, uint ba = 0);

ガベージコレクタの管理するメモリに、 alignされたゼロクリア済みブロックを要求します。このメモリはfreeを呼び出して明示的にdeleteすることも、コレクタの実行によって自動的に回収することも可能です。割り当てが失敗した場合、onOutOfMemory 関数を呼び出し、そこで通常は OutOfMemoryException 例外が投げられます。

Params:

size_t sz	割り当てたいバイト数
uint ba	このブロックにセットするビットマスク

Returns:
割り当てられたメモリへの参照。十分なメモリが無かった場合は null を返します。

Throws:
割り当て失敗時に OutOfMemoryException

static void* realloc(void* p, size_t sz, uint ba = 0);

sz がゼロの時は、free の呼び出しと同じように p の指すメモリブロックが解放されます。それ以外の場合は、サイズ sz のブロックが malloc のように確保されるか、または実装によっては、位置を変えずにブロックがリサイズされます。新しいメモリブロックの内容は、新旧ブロックのサイズの小さい方までは、まったく同じ内容がコピーされます。realloc によって元のメモリ領域が開放されるのは sz がゼロの時であることに注意してください。それ以外の場合は、使用されていない領域は後でガベージコレクタが回収します。割り当てが失敗した場合、onOutOfMemory 関数を呼び出し、そこで通常は OutOfMemoryException 例外が投げられます。p がこのGCでアロケートされたメモリを指していない場合、あるいはメモリブロックの途中を指している場合、または p が null の場合は、何も起きません。 ba がゼロ (デフォルト) で p が有効な既存のメモリブロックの先頭を指している場合、元のブロックに設定されていたビットが新しいブロックにもそのまま適用されます。 ba がゼロでなく p が有効な既存のメモリブロックの先頭を指している場合、 ba のビットが元のブロックのビットを置き換え、さらに新しい再割り当てが必要な場合は新しいブロックにも設定されます。

Params:

void* p	有効なメモリブロックのルートへのポインタ、もしくは null
size_t sz	割り当てたいバイト数
uint ba	このブロックにセットするビットマスク

Returns:
割り当てられたメモリへの参照。sz がゼロの場合は null、失敗時には元の p の値を返します。

Throws:
割り当て失敗時に OutOfMemoryException

static size_t extend(void* p, size_t mx, size_t sz);

p の指すGCの管理するメモリブロックのサイズを、最低 mx バイト以上、可能なら sz バイト拡張します。要求サイズを満たせなかった場合や、p がこのGCでアロケートされたメモリを指していない場合、あるいはメモリブロックの途中を指している場合は、何も起きません。

Params:

size_t mx	最低拡張サイズ。バイト数で指定
size_t sz	期待する拡張サイズ。バイト数で指定

Returns:
拡張されたブロックのサイズ。拡張が行われなかった場合は0。

static size_t reserve(size_t sz);

最低 sz バイトのメモリ領域がOSから確保され、フリー領域としてマークされている状態になるよう保証します。

Params:

size_t sz

要求サイズ。バイト数で指定

Returns:
実際に確保されたバイト数。エラー時は0。

static void free(void* p);

p の指すメモリブロックを解放します。p が null の場合は何も起きません。 p がこのGCでアロケートされたメモリを指していない場合、あるいはメモリブロックの途中を指している場合も、何も起きません。FINALIZE 属性の状態にかかわらず、 freeで解放した場合はファイナライザは実行されません。ファイナライザが必要な場合は delete を使用します。

Params:

void* p

有効なメモリブロックへのポインタ、または null

static void* addrOf(in void* p);

p を含むメモリブロックのベースアドレスを返します。この返値は、p がブロック内部を指すポインタかどうか判断するのに役立ち、 sizeOf などのベースアドレスのみを受け取る関数へ渡す値として使うことが出来ます。 p がこのGCでアロケートされたメモリを指していない場合、 p が null の場合、あるいはGCがこの操作に対応していない場合、 null が返ります。

Params:

void* p

メモリブロックの内部あるいはベースポインタ、もしくは null

Returns:
p を含むメモリブロックのベース。エラー時は null。

static size_t sizeOf(in void* p);

p の指すメモリブロックの真のサイズ。 This value この値は、realloc 等で位置を変えずにブロックを拡張できる最大サイズを表します。 p がこのGCでアロケートされたメモリを指していない場合、メモリブロックの途中を指している場合、または p が null の場合は、ゼロを返します。

Params:

void* p

メモリブロックのベースポインタあるいは null。

Returns:
p の指すメモリブロックの最大サイズ。エラー時は0。

static BlkInfo query(in void* p);

pを含むメモリブロックの情報を集めて返します。 p がこのGCでアロケートされたメモリを指していない場合、 p が null の場合、またはGCがこの操作に対応していない場合は、 BlkInfo.init を返します。典型的な実装では、この操作への対応は addrOf への対応に依存します。

Params:

void* p

メモリブロックの内部あるいはベースポインタ、もしくは null

Returns:
p の指すメモリブロックの情報。エラー時は BlkInfo.init。

static void addRoot(in void* p);

p の指すメモリブロックを、メモリ回収時にスキャンするルートブロックとしてGCの内部リストに追加します。 p が null の場合、何も起きません。

Params:

void* p

有効なメモリブロックを指すポインタもしくは null

static void addRange(in void* p, size_t sz);

p の指す、サイズszのメモリブロックを、モリ回収時にスキャンするルートブロックとしてGCの内部リストに追加します。 p が null の場合、何も起きません。

Params:

void* p	有効なメモリアドレスを指すポインタもしくは null
size_t sz	追加するブロックのバイト数。sz がゼロならば何も行われません。 p が null の場合 sz はゼロでなければなりません。

static void removeRoot(in void* p);

p から参照されているメモリブロックを、スキャン対象のルートブロックリストから取り除きます。p が null か、 add(void*) に渡されたことのない値である場合、何も起きません。

p 有効なメモリアドレスを指すポインタもしくは null

static void removeRange(in void* p);

p から参照されているメモリブロックを、スキャン対象のルートブロックリストから取り除きます。p が null か、 add(void*, size_t) に渡されたことのない値である場合、何も起きません。

Params:

void* p

有効なメモリアドレスを指すポインタもしくは null