![]() |
![]() |
![]() |
libInstPatch Reference Manual | ![]() |
---|---|---|---|---|
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);
GObject +----IpatchItem +----IpatchFile +----IpatchContainer +----IpatchDLS2Sample +----IpatchDLS2Region +----IpatchGigDimension +----IpatchGigSubRegion +----IpatchSampleStore +----IpatchSF2Sample +----IpatchSF2Zone
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.
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 |
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;
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.
#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.
#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 |
#define IPATCH_ITEM_WUNLOCK(item)
Write unlocks an item that was previously locked with IPATCH_ITEM_WLOCK()
.
item : |
Item to write unlock |
#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 |
#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 |
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). |
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 |
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 |
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. |
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 |
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).
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.
|
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.
|
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.
|
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.
|
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.
|
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 |
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 |
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 |
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 |
gboolean ipatch_item_copy (IpatchItem *dest, IpatchItem *src, GHashTable *replace, GError **err);
dest : |
|
src : |
|
replace : |
|
err : |
|
Returns : |
IpatchItem* ipatch_item_duplicate (IpatchItem *item, GHashTable *replace, GError **err);
item : |
|
replace : |
|
err : |
|
Returns : |
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.
|
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.
|
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.
|
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.
|
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 |