SquashObject

Base object for several Squash types. More...

Data Structures
struct	_SquashObject
	Reference-counting base class for other types. More...

Typedefs
typedef void(*	SquashDestroyNotify) (void *data)
	Callback to be invoked when information data is no longer needed. More...

Functions
void *	squash_object_ref (void *obj)
	Increment the reference count on an object. More...
void *	squash_object_ref_sink (void *obj)
	Sink a floating reference if one exists. More...
void *	squash_object_unref (void *obj)
	Decrement the reference count on an object. More...
unsigned int	squash_object_get_ref_count (void *obj)
	Get the current reference count of an object. More...
void	squash_object_init (void *obj, bool is_floating, SquashDestroyNotify destroy_notify)
	Initialize a new object. More...
void	squash_object_destroy (void *obj)
	Destroy an object. More...

Detailed Description

Base object for several Squash types.

SquashObject is designed to provide a lightweight reference-counted type which can be used as a base class for other types in Squash.

Subclassing

Subclassing SquashObject is relatively straightforward. The first step is to embed SquashObject in your object. Assuming you're inheriting directly from SquashObject, your code would look something like this:

struct MyObject {
  SquashObject base_object;
  char* greeting;
}

If you are subclassing another type (which inherits, possibly indirectly, from SquashObject) then you should use that type instead.

Next, you should to create an *_init function which takes an existing instance of your class, chains up to the *_init function provided by your base class, and initializes any fields you want initialized:

void
my_object_init (MyObject* obj,
                char* greeting,
                SquashDestroyNotify destroy_notify) {
  squash_object_init ((SquashObject*) obj, false, destroy_notify);

  obj->greeting = strdup (greeting);
}

Of course, whatever is created must be destroyed, so you'll also want to create a *_destroy method to be called when the reference count reaches 0. Destroy any of your fields first, then chain up to the base class' *_destroy function:

void
my_object_destroy (MyObject* obj) {
  if (obj->greeting != NULL) {
    free (obj->greeting);
  }

  squash_object_destroy (obj);
}

If your class is not abstract (it is meant to be instantiated, not just subclassed), you should create two more functions. First, a *_free function which will call your *_destroy function and release any memory you've allocated for the struct itself:

void
my_object_free (MyObject* obj) {
  my_object_destroy (obj);
  free (obj);
}

Finally, a constructor:

MyObject*
my_object_new (char* greeting) {
  MyObject obj;

  obj = malloc (sizeof (MyObject));
  my_object_init (obj, greeting, (SquashDestroyNotify) my_object_free);

  return obj;
}

Typedef Documentation

SquashDestroyNotify

Callback to be invoked when information data is no longer needed.

When you are not subclassing SquashObject, SquashDestroyNotify is used almost exclusively for memory management, most simply by passing free().

Definition at line 43 of file object.h.

Function Documentation

void squash_object_destroy ( void *  obj )

protected

Destroy an object.

This function should only be used to implement a subclass of SquashObject. Each subclass should implement a *_destroy function which should perform any operations needed to destroy their own data and chain up to the *_destroy function of the base class, eventually invoking squash_object_destroy.

Parameters

obj	The object to destroy.

Definition at line 325 of file object.c.

unsigned int squash_object_get_ref_count

(

void *

obj

)

Get the current reference count of an object.

Parameters

obj	The object in question.

Returns

The reference count of obj.

Definition at line 280 of file object.c.

void squash_object_init ( void *  obj, bool  is_floating, SquashDestroyNotify  destroy_notify  )

protected

Initialize a new object.

This function should only be used to implement a subclass of SquashObject. Objects returned by *_new functions will already be initialized, and you must not call this function on them.

Parameters

obj	The object to initialize.
is_floating	Whether or not the object's reference is floating
destroy_notify	Function to call when the reference count reaches 0

Definition at line 302 of file object.c.

void* squash_object_ref

(

void *

obj

)

Increment the reference count on an object.

Parameters

obj	The object to increase the reference count of.

Returns

The object which was passed in.

Definition at line 206 of file object.c.

void* squash_object_ref_sink

(

void *

obj

)

Sink a floating reference if one exists.

If a floating reference exists on the object, sink it.

For a description of how floating references work, see GObject's documentation of the concept. The implementation here is different, but the concept remains the same.

Parameters

obj	The object to sink the floating reference on.

Returns

The object which was passed in.

Definition at line 237 of file object.c.

void* squash_object_unref

(

void *

obj

)

Decrement the reference count on an object.

Once the reference count reaches 0 the object will be freed.

Parameters

obj	The object to decrease the reference count of.

Returns

NULL

Definition at line 255 of file object.c.