管理下オブジェクト

参照回数で管理されるオブジェクト [詳解]

データ構造
struct	M17NObjectHead
	管理下オブジェクトの最初のメンバ. [詳解]

関数
void *	m17n_object (int size, void(*freer)(void *))
int	m17n_object_ref (void *object)
	管理下オブジェクトの参照数を 1 増やす.
int	m17n_object_unref (void *object)
	管理下オブジェクトの参照数を 1 減らす.

詳解

参照回数で管理されるオブジェクト

管理下オブジェクトとは参照数によって管理されているオブジェクトである.

m17n オブジェクトのある型のものは、参照数によって管理されている。 それらのオブジェクトは 管理下オブジェクト と呼ばれる。生成された時点での参照数は 1 に初期化されている。関数 m17n_object_ref() は管理下オブジェクトの参照数を 1 増やし、関数m17n_object_unref() は 1 減らす。参照数が 0 になった管理下オブジェクトは自動的に解放される。

キーが管理キーであるプロパティは、値として管理下オブジェクトだけを取る。 関数 msymbol_put() や mplist_put() などはそれらのプロパティを特別扱いする。

定義済み管理下オブジェクトタイプの他に、ユーザは必要な管理下オブジェクトタイプを自分で定義することができる。詳細は m17n_object() の説明を参照。

関数詳解

m17n_object()

void * m17n_object	(	int	size,
		void(*)(void *)	freer
	)

@brief 管理下オブジェクトを割り当てる.

関数 m17n_object() は@b size バイトの新しい管理下オブジェクトを割り当て、その参照数を
1 とする。 @b freer は参照数が 0 
になった際にそのオブジェクトを解放するために用いられる関数である。@b freer
が NULLならば、オブジェクトは関数 free() によって解放される。

割り当てられたオブジェクト冒頭のバイトは、#M17NObjectHead 
が占める。この領域は m17n ライブラリが使用するので、アプリケーションプログラムは触れてはならない。

@par 戻り値:
この関数は新しく割り当てられたオブジェクトを返す。

@par エラー:
この関数は失敗しない。

例：

typedef struct
{
  M17NObjectHead head;
  int mem1;
  char *mem2;
} MYStruct;
 
void
my_freer (void *obj)
{
  free (((MYStruct *) obj)->mem2);
  free (obj);
}
 
void
my_func (MText *mt, MSymbol key, int num, char *str)
{
  MYStruct *st = m17n_object (sizeof (MYStruct), my_freer);
 
  st->mem1 = num;
  st->mem2 = strdup (str);
  /* KEY must be a managing key.   */
  mtext_put_prop (mt, 0, mtext_len (mt), key, st);
  /* This sets the reference count of ST back to 1.  */
  m17n_object_unref (st);
}

m17n_object_ref()

int m17n_object_ref

(

void *

object

)

管理下オブジェクトの参照数を 1 増やす.

関数 m17n_object_ref() は object で指される管理下オブジェクトの参照数を 1 増やす。

戻り値:

この関数は、増やした参照数が 16 ビットの符号無し整数値(すなわち 0x10000 未満)におさまれば、それを返す。そうでなければ -1 を返す。

エラー:

この関数は失敗しない。

m17n_object_unref()

int m17n_object_unref

(

void *

object

)

管理下オブジェクトの参照数を 1 減らす.

関数 m17n_object_unref() は object で指される管理下オブジェクトの参照数を 1 減らす。参照数が 0 になれば、オブジェクトは解放関数によって解放される。

戻り値:

この関数は、減らした参照数が 16 ビットの符号無し整数値(すなわち 0x10000 未満)におさまれば、それを返す。そうでなければ -1 を返す。つまり、0 が返って来た場合はobject は解放されている。

エラー:

この関数は失敗しない。