IpatchItem

IpatchItem — Base abstract class for all patch items.

Synopsis




void                (*IpatchItemPropNotifyHook)         (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         const GValue *new_value);
                    IpatchItem;
                    IpatchItemClass;
enum                IpatchItemFlags;
#define             IPATCH_ITEM_UNUSED_FLAG_SHIFT
#define             IPATCH_ITEM_FLAGS                   (item)
#define             IPATCH_ITEM_SET_FLAGS               (item, f)
#define             IPATCH_ITEM_CLEAR_FLAGS             (item, f)
#define             IPATCH_ITEM_WLOCK                   (item)
#define             IPATCH_ITEM_WUNLOCK                 (item)
#define             IPATCH_ITEM_RLOCK                   (item)
#define             IPATCH_ITEM_RUNLOCK                 (item)
guint32             ipatch_item_get_flags               (IpatchItem *item);
void                ipatch_item_set_flags               (IpatchItem *item,
                                                         int flags);
void                ipatch_item_clear_flags             (IpatchItem *item,
                                                         int flags);
void                ipatch_item_set_parent              (IpatchItem *item,
                                                         IpatchItem *parent);
void                ipatch_item_unparent                (IpatchItem *item);
IpatchItem*         ipatch_item_ref_parent              (IpatchItem *item);
IpatchItem*         ipatch_item_peek_parent             (IpatchItem *item);
IpatchItem*         ipatch_item_ref_base                (IpatchItem *item);
IpatchItem*         ipatch_item_peek_base               (IpatchItem *item);
IpatchItem*         ipatch_item_ref_ancestor_type       (IpatchItem *item,
                                                         GType ancestor_type);
IpatchItem*         ipatch_item_peek_ancestor_type      (IpatchItem *item,
                                                         GType ancestor_type);
void                ipatch_item_remove                  (IpatchItem *item);
void                ipatch_item_changed                 (IpatchItem *item);
void                ipatch_item_prop_notify             (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         const GValue *new_value);
void                ipatch_item_prop_notify_by_name     (IpatchItem *item,
                                                         const char *prop_name,
                                                         const GValue *new_value);
gboolean            ipatch_item_copy                    (IpatchItem *dest,
                                                         IpatchItem *src,
                                                         GHashTable *replace,
                                                         GError **err);
IpatchItem*         ipatch_item_duplicate               (IpatchItem *item,
                                                         GHashTable *replace,
                                                         GError **err);
void                ipatch_item_set_atomic              (gpointer item,
                                                         const char *first_property_name,
                                                         ...);
void                ipatch_item_get_atomic              (gpointer item,
                                                         const char *first_property_name,
                                                         ...);
IpatchItem*         ipatch_item_first                   (IpatchIter *iter);
IpatchItem*         ipatch_item_next                    (IpatchIter *iter);
void                ipatch_item_set_prop_notify_hook    (IpatchItemPropNotifyHook hook_func);

Object Hierarchy


  GObject
   +----IpatchItem
         +----IpatchFile
         +----IpatchContainer
         +----IpatchDLS2Sample
         +----IpatchDLS2Region
         +----IpatchGigDimension
         +----IpatchGigSubRegion
         +----IpatchSampleStore
         +----IpatchSF2Sample
         +----IpatchSF2Zone

Description

This is the base class that all patch items are derived from. It provides multi-thread locking and defines a child/parent relationship between items.

Details

IpatchItemPropNotifyHook ()

void                (*IpatchItemPropNotifyHook)         (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         const GValue *new_value);

A function prototype for hooking item property changes. When assigned to the IpatchItemClass prop_change_hook method field - this function will be called before every IpatchItem property change.

item : Item whose property is being changed
pspec : The parameter spec of the property that is changing
new_value : The new value that will be assigned to the property

IpatchItem

typedef struct _IpatchItem IpatchItem;


IpatchItemClass

typedef struct {
  GObjectClass parent_class;


  gboolean mutex_slave;	/* set to TRUE to use parent thread mutex */

  /* methods */
  void (*item_set_property)(GObject *object, guint property_id,
			    const GValue *value, GParamSpec *pspec);
  gboolean (*copy)(IpatchItem *dest, IpatchItem *src, GHashTable *replace,
		   GError **err);
  void (*remove)(IpatchItem *item);

  /* virtual function hook callbacks */

  /* called prior to IpatchItem property change */
  IpatchItemPropNotifyHook pre_prop_notify_hook;

  /* called after IpatchItem property change */
  IpatchItemPropNotifyHook prop_notify_hook;
} IpatchItemClass;


enum IpatchItemFlags

typedef enum /*< flags >*/
{
  IPATCH_ITEM_HOOKS_ACTIVE = 1 << 0,  /* hook callbacks active? */
  IPATCH_ITEM_FREE_MUTEX   = 1 << 1   /* TRUE if item should free its mutex */
} IpatchItemFlags;

Flags for IpatchItem objects.


IPATCH_ITEM_UNUSED_FLAG_SHIFT

#define IPATCH_ITEM_UNUSED_FLAG_SHIFT 4

Shift value for next free flag position. Useful for derived types to define their own flags without wasting memory on their own flags field.


IPATCH_ITEM_FLAGS()

#define IPATCH_ITEM_FLAGS(item)  (((IpatchItem *)(item))->flags)

item :

IPATCH_ITEM_SET_FLAGS()

#define             IPATCH_ITEM_SET_FLAGS(item, f)

item :
f :

IPATCH_ITEM_CLEAR_FLAGS()

#define             IPATCH_ITEM_CLEAR_FLAGS(item, f)

item :
f :

IPATCH_ITEM_WLOCK()

#define             IPATCH_ITEM_WLOCK(item)

Write locks an item for multi-thread critical writes.

This macro is recursive, which means that a thread can issue multiple locks on the same item, but needs to unlock it the same number of times.

item : Item to write lock

IPATCH_ITEM_WUNLOCK()

#define             IPATCH_ITEM_WUNLOCK(item)

Write unlocks an item that was previously locked with IPATCH_ITEM_WLOCK().

item : Item to write unlock

IPATCH_ITEM_RLOCK()

#define IPATCH_ITEM_RLOCK(item)		IPATCH_ITEM_WLOCK(item)

Read locks an item for multi-thread critical reads.

This macro is recursive, which means that a thread can issue multiple locks on the same item, but needs to unlock it the same number of times.

item : Item to read lock

IPATCH_ITEM_RUNLOCK()

#define IPATCH_ITEM_RUNLOCK(item)	IPATCH_ITEM_WUNLOCK(item)

Read unlocks an item that was previously locked with IPATCH_ITEM_RLOCK().

item : Item to read unlock

ipatch_item_get_flags ()

guint32             ipatch_item_get_flags               (IpatchItem *item);

Get the value of the flags field in a patch item.

item : Item to get flag field from
Returns : Value of 32 bit flag field (some of which is user definable).

ipatch_item_set_flags ()

void                ipatch_item_set_flags               (IpatchItem *item,
                                                         int flags);

Set flags in a patch item. All bits that are set in flags are set in the item flags field.

item : Item to set flags in
flags : Flags to set

ipatch_item_clear_flags ()

void                ipatch_item_clear_flags             (IpatchItem *item,
                                                         int flags);

Clear (unset) flags in a patch item. All bits that are set in flags are cleared in the item flags field.

item : Item object to clear flags in
flags : Flags to clear

ipatch_item_set_parent ()

void                ipatch_item_set_parent              (IpatchItem *item,
                                                         IpatchItem *parent);

Usually only used by IpatchItem type implementations. Sets the parent of a patch item. Also recursively sets base parent and IPATCH_ITEM_HOOKS_ACTIVE flag if set in parent. Also assigns the item's thread mutex to that of the parent if its class has mutex_slave set. The parent container is responsible for adding a reference to item - this function does not do so.

NOTE: If the item has mutex_slave set in its class then the item will use parent object's mutex. During the call to this function item should not be accessed by any other threads, otherwise problems may occur when the mutex is changed. Normally this shouldn't be much of an issue, since new item's are often only accessed by 1 thread until being parented.

item : Item to set parent of (should not have a parent).
parent : New parent of item.

ipatch_item_unparent ()

void                ipatch_item_unparent                (IpatchItem *item);

Usually only used by IpatchItem type implementations. Unparent an item. Also recursively unsets base parent and IPATCH_ITEM_HOOKS_ACTIVE flag. Parent container object is responsible for removing reference of item - this function does not do so.

item : Item to unparent

ipatch_item_ref_parent ()

IpatchItem*         ipatch_item_ref_parent              (IpatchItem *item);

Gets the parent of item after incrementing its reference count. The caller is responsible for decrementing the reference count with g_object_unref when finished with it. This function is useful because all code paths must contain references to the items that they are working with in a multi-thread environment (there is no guarantee an item won't be destroyed unless a refcount is held).

item : Item to get parent of
Returns : The parent of item or NULL if not parented or a root item. If not NULL then the reference count of parent has been incremented and the caller is responsible for removing it when finished with parent.

ipatch_item_peek_parent ()

IpatchItem*         ipatch_item_peek_parent             (IpatchItem *item);

This function is the same as ipatch_item_ref_parent() (gets an item's parent) but does not increment the parent's ref count. Therefore this function should only be used when the caller already holds a reference or when only the value of the pointer will be used (not the contents), to avoid multi-thread problems.

item : Item to get the parent of
Returns : The parent of item or NULL if not parented or a root item.

ipatch_item_ref_base ()

IpatchItem*         ipatch_item_ref_base                (IpatchItem *item);

Gets the base parent of item (toplevel patch file object) after incrementing its reference count. The caller is responsible for decrementing the reference count with g_object_unref when finished with it. If item is itself a IpatchBase object then it is returned.

item : Item to get base parent of
Returns : The base parent of item or NULL if no IpatchBase type in parent ancestry. If not NULL then the reference count of parent has been incremented and the caller is responsible for removing it when finished with the base parent.

ipatch_item_peek_base ()

IpatchItem*         ipatch_item_peek_base               (IpatchItem *item);

This function is the same as ipatch_item_ref_base() (gets an item's toplevel base parent) but does not increment the parent's ref count. Therefore this function should only be used when the caller already holds a reference or when only the value of the pointer will be used (not the contents), to avoid multi-thread problems.

item : Item to get the base parent of
Returns : The base parent of item or NULL if no IpatchBase type in parent ancestry.

ipatch_item_ref_ancestor_type ()

IpatchItem*         ipatch_item_ref_ancestor_type       (IpatchItem *item,
                                                         GType ancestor_type);

Searches for the first parent item that is derived from ancestor_type in the item object's ancestry. ancestor_type must be an IpatchItem derived type (as well as the ancestry of item). Of note is that item can also match. The returned item's reference count has been incremented and it is the responsiblity of the caller to remove it with g_object_unref() when finished with it.

item : Item to search for parent of a given type
ancestor_type : Type of parent in the item object's ancestry
Returns : The matched item (can be the item itself) or NULL if no item matches ancestor_type in the ancestry. Remember to unref the matched item when done with it.

ipatch_item_peek_ancestor_type ()

IpatchItem*         ipatch_item_peek_ancestor_type      (IpatchItem *item,
                                                         GType ancestor_type);

Just like ipatch_item_ref_ancestor_type() but doesn't ref returned item. This is only useful when caller already owns a reference or only the pointer value is of importance.

item : Item to search for parent of a given type
ancestor_type : Type of parent in the item object's ancestry
Returns : The matched item (can be the item itself) or NULL if no item matches ancestor_type in the ancestry. Remember that the returned item is not referenced.

ipatch_item_remove ()

void                ipatch_item_remove                  (IpatchItem *item);

This function removes an item from its parent container and removes other references from within the same patch (e.g., a IpatchSF2Sample will be removed from its parent IpatchSF2 and all IpatchSF2IZone objects referencing the sample will also be removed).

item : Item to remove

ipatch_item_changed ()

void                ipatch_item_changed                 (IpatchItem *item);

This function should be called when an item's saveable state (what ends up in a patch file) has changed. Causes the item object's base parent to have its changed flag set, indicating that the file has changes that have not been saved.

item : Item that has changed

ipatch_item_prop_notify ()

void                ipatch_item_prop_notify             (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         const GValue *new_value);

Usually only used by IpatchItem object implementations, rather than explicitly called by the user. Calls an item object's "prop_notify_hook" function. It should be called before item property changes that occur outside of the IpatchItem item_set_property method.

item : Item whose property will change
pspec : Parameter specification for item of parameter being changed
new_value : The new value being assigned

ipatch_item_prop_notify_by_name ()

void                ipatch_item_prop_notify_by_name     (IpatchItem *item,
                                                         const char *prop_name,
                                                         const GValue *new_value);

Usually only used by IpatchItem object implementations, rather than explicitly called by the user. Like ipatch_item_prop_notify() except takes a property name instead of a parameter spec, for convenience.

item : Item whose property will change
prop_name : Name of property being changed
new_value : The new value being assigned

ipatch_item_copy ()

gboolean            ipatch_item_copy                    (IpatchItem *dest,
                                                         IpatchItem *src,
                                                         GHashTable *replace,
                                                         GError **err);

dest :
src :
replace :
err :
Returns :

ipatch_item_duplicate ()

IpatchItem*         ipatch_item_duplicate               (IpatchItem *item,
                                                         GHashTable *replace,
                                                         GError **err);

item :
replace :
err :
Returns :

ipatch_item_set_atomic ()

void                ipatch_item_set_atomic              (gpointer item,
                                                         const char *first_property_name,
                                                         ...);

Sets properties on a patch item atomically (i.e. item is multi-thread locked while all properties are set). This avoids critical parameter sync problems when multiple threads are accessing the same item. See g_object_set() for more information on setting properties.

item : IpatchItem derived object to set properties of
first_property_name : Name of first property
... : Variable list of arguments that should start with the value to set first_property_name to, followed by property name/value pairs. List is terminated with a NULL property name.

ipatch_item_get_atomic ()

void                ipatch_item_get_atomic              (gpointer item,
                                                         const char *first_property_name,
                                                         ...);

Gets properties from a patch item atomically (i.e. item is multi-thread locked while all properties are retrieved). This avoids critical parameter sync problems when multiple threads are accessing the same item. See g_object_get() for more information on getting properties.

item : IpatchItem derived object to get properties from
first_property_name : Name of first property
... : Variable list of arguments that should start with a pointer to store the value from first_property_name, followed by property name/value pointer pairs. List is terminated with a NULL property name.

ipatch_item_first ()

IpatchItem*         ipatch_item_first                   (IpatchIter *iter);

Gets the first item in a patch item iterator. A convenience wrapper for ipatch_iter_first().

iter : Patch item iterator containing IpatchItem items
Returns : The first item in iter or NULL if empty.

ipatch_item_next ()

IpatchItem*         ipatch_item_next                    (IpatchIter *iter);

Gets the next item in a patch item iterator. A convenience wrapper for ipatch_iter_next().

iter : Patch item iterator containing IpatchItem items
Returns : The next item in iter or NULL if no more items.

ipatch_item_set_prop_notify_hook ()

void                ipatch_item_set_prop_notify_hook    (IpatchItemPropNotifyHook hook_func);

Set the IpatchItem property notify hook function. This function will be executed for property changes on IpatchItem objects with the IPATCH_ITEM_HOOKS_ACTIVE flag set.

MT-NOTE: Setting to NULL is not multi-thread safe.

hook_func : Hook callback function