Managed Object

Objects managed by the reference count
More...

Data Structures
struct	M17NObjectHead
	The first member of a managed object. More...

Functions
void *	m17n_object (int size, void(*freer)(void *))
int	m17n_object_ref (void *object)
	Increment the reference count of a managed object.
int	m17n_object_unref (void *object)
	Decrement the reference count of a managed object.

Detailed Description

Objects managed by the reference count

Managed objects are objects managed by the reference count.

There are some types of m17n objects that are managed by their reference count. Those objects are called managed objects. When created, the reference count of a managed object is initialized to one. The m17n_object_ref() function increments the reference count of a managed object by one, and the m17n_object_unref() function decrements by one. A managed object is automatically freed when its reference count becomes zero.

A property whose key is a managing key can have only a managed object as its value. Some functions, for instance msymbol_put() and mplist_put(), pay special attention to such a property.

In addition to the predefined managed object types, users can define their own managed object types. See the documentation of the m17n_object() for more details.

Function Documentation

m17n_object()

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

@brief Allocate a managed object.

The m17n_object() function allocates a new managed object of
@b size bytes and sets its reference count to 1.  @b freer is the
function that is used to free the object when the reference count
becomes 0.  If @b freer is NULL, the object is freed by the free()
function.

The heading bytes of the allocated object is occupied by
#M17NObjectHead.  That area is reserved for the m17n library and
application programs should never touch it.

@par Return value:
This function returns a newly allocated object.

@par Errors:
This function never fails.   

Example:

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

)

Increment the reference count of a managed object.

The m17n_object_ref() function increments the reference count of the managed object pointed to by object.

Return value:

This function returns the resulting reference count if it fits in a 16-bit unsigned integer (i.e. less than 0x10000). Otherwise, it return -1.

Errors:

This function never fails.

m17n_object_unref()

int m17n_object_unref

(

void *

object

)

Decrement the reference count of a managed object.

The m17n_object_unref() function decrements the reference count of the managed object pointed to by object. When the reference count becomes zero, the object is freed by its freer function.

Return value:

This function returns the resulting reference count if it fits in a 16-bit unsigned integer (i.e. less than 0x10000). Otherwise, it returns -1. Thus, the return value zero means that object is freed.

Errors:

This function never fails.