 |
 |
 |
Data Model API (libmodel) |  |
|---|---|---|---|---|
| Top | Description | ||||
ModelReferenceHelperModelReferenceHelper — a way to control object life-cycle when using ModelReference objects |
Synopsis
ModelReferenceHelper; ModelReference * model_reference_helper_get_reference (ModelReferenceHelper *helper); ModelReferenceHelper * model_reference_helper_new (GObject *owner, ModelObject *value); void model_reference_helper_set (ModelReferenceHelper *helper, ModelObject *value); ModelReferenceHelper * model_reference_helper_new_string (GObject *owner, const gchar *value); ModelReferenceHelper * model_reference_helper_new_integer (GObject *owner, gint value); ModelReferenceHelper * model_reference_helper_new_float (GObject *owner, gdouble value); ModelReferenceHelper * model_reference_helper_new_boolean (GObject *owner, gboolean value); void model_reference_helper_set_string (ModelReferenceHelper *helper, const gchar *value); void model_reference_helper_set_integer (ModelReferenceHelper *helper, gint value); void model_reference_helper_set_float (ModelReferenceHelper *helper, gdouble value); void model_reference_helper_set_boolean (ModelReferenceHelper *helper, gboolean value);
Description
When using ModelSimpleReference to create ModelReference objects, a problem often arises. The part of the model ("the source object") that is responsible for monitoring the data source and updating the ModelReference holds a strong reference on the ModelSimpleReference. This means that the ModelReference can not hold a strong reference on the source object and that, once remaining outside references to the source object are dropped, it will be finalized. This finalization occurs even if there are users of the model still monitoring the ModelReference for changes -- changes that will now no longer be delivered.
ModelReferenceHelper introduces a 3rd object to resolve this
situation. The reference helper (blue in the diagram) is held (by
strong reference) by the source object (orange). The reference
helper has only a weak reference to the source object. Just like a
ModelSimpleReference, the reference helper keeps a strong reference
to the value of the reference (green). When
model_reference_helper_get_reference() is called, a ModelReference
(ping) is created that holds a strong reference to the source object.
The source object is kept alive to update the reference for as long
as the reference exists.
The core API of ModelReferenceHelper consists of
model_reference_helper_new(), model_reference_helper_set() and
model_reference_helper_get_reference(). Additionally, there are
helper functions to set and construct from one of the basic value
types without requiring the manual construction of a corresponding
ModelObject instance.
Details
ModelReferenceHelper
typedef struct _ModelReferenceHelper ModelReferenceHelper;
This is an opaque structure; it may not be accessed directly.
model_reference_helper_get_reference ()
ModelReference * model_reference_helper_get_reference (ModelReferenceHelper *helper);
Creates and returns a ModelReference object for the value stored in
helper. Any ModelReference created with this function will have
its "changed" signal emitted when model_reference_helper_set() is
called on helper.
This function is not thread-safe with respect to g_object_unref()
being called in other threads. See bug 548954 for why.
|
a ModelReferenceHelper Returns: a ModelReference |
model_reference_helper_new ()
ModelReferenceHelper * model_reference_helper_new (GObject *owner, ModelObject *value);
Creates a new model reference helper for use with owner. The
initial value of the helper is value.
|
the "owner" GObject |
|
the ModelObject with the initial value |
|
a new ModelReferenceHelper |
model_reference_helper_set ()
void model_reference_helper_set (ModelReferenceHelper *helper, ModelObject *value);
Changes the value held by helper to value.
If the helper has outstanding references (as returned by
model_reference_helper_get_reference()) then the "changed" signal
will be emitted on them.
|
a ModelReferenceHelper |
|
the ModelObject to use as the new value, or NULL
|
model_reference_helper_new_string ()
ModelReferenceHelper * model_reference_helper_new_string (GObject *owner, const gchar *value);
Creates a new ModelReferenceHelper holding a string.
This is a convenience wrapper around model_reference_helper_new() and
model_string_new().
|
the "owner" GObject |
|
a string |
|
a new ModelReferenceHelper |
model_reference_helper_new_integer ()
ModelReferenceHelper * model_reference_helper_new_integer (GObject *owner, gint value);
Creates a new ModelReferenceHelper holding an integer.
This is a convenience wrapper around model_reference_helper_new() and
model_integer_new().
|
the "owner" GObject |
|
an integer |
|
a new ModelReferenceHelper |
model_reference_helper_new_float ()
ModelReferenceHelper * model_reference_helper_new_float (GObject *owner, gdouble value);
Creates a new ModelReferenceHelper holding a floating point value.
This is a convenience wrapper around model_reference_helper_new() and
model_float_new().
|
the "owner" GObject |
|
a double precision floating point value |
|
a new ModelReferenceHelper |
model_reference_helper_new_boolean ()
ModelReferenceHelper * model_reference_helper_new_boolean (GObject *owner, gboolean value);
Creates a new ModelReferenceHelper holding a boolean value.
This is a convenience wrapper around model_reference_helper_new() and
model_boolean_new().
|
the "owner" GObject |
|
a boolean value |
|
a new ModelReferenceHelper |
model_reference_helper_set_string ()
void model_reference_helper_set_string (ModelReferenceHelper *helper, const gchar *value);
Updates the value of helper to the given string.
This is a convenience wrapper around model_reference_helper_set() and
model_string_new().
|
a ModelReferenceHelper |
|
a string |
model_reference_helper_set_integer ()
void model_reference_helper_set_integer (ModelReferenceHelper *helper, gint value);
Updates the value of helper to the given integer.
This is a convenience wrapper around model_reference_helper_set() and
model_integer_new().
|
a ModelReferenceHelper |
|
an integer |
model_reference_helper_set_float ()
void model_reference_helper_set_float (ModelReferenceHelper *helper, gdouble value);
Updates the value of helper to the given floating point value.
This is a convenience wrapper around model_reference_helper_set() and
model_float_new().
|
a ModelReferenceHelper |
|
a double precision floating point value |
model_reference_helper_set_boolean ()
void model_reference_helper_set_boolean (ModelReferenceHelper *helper, gboolean value);
Updates the value of helper to the given boolean value.
This is a convenience wrapper around model_reference_helper_set() and
model_boolean_new().
|
a ModelReferenceHelper |
|
a boolean value |