camel-object-bag

camel-object-bag

Types and Values

Description

Functions

CamelCopyFunc ()

gpointer
(*CamelCopyFunc) (gconstpointer object);

camel_object_bag_new ()

CamelObjectBag *
camel_object_bag_new (GHashFunc key_hash_func,
                      GEqualFunc key_equal_func,
                      CamelCopyFunc key_copy_func,
                      GFreeFunc key_free_func);

Returns a new object bag. Object bags are keyed hash tables of objects that can be updated atomically using transaction semantics. Use camel_object_bag_destroy() to free the object bag.

Parameters

key_hash_func

a hashing function for keys.

[scope call]

key_equal_func

a comparison function for keys.

[scope call]

key_copy_func

a function to copy keys.

[scope call]

key_free_func

a function to free keys.

[scope call]

Returns

a newly-allocated CamelObjectBag


camel_object_bag_get ()

gpointer
camel_object_bag_get (CamelObjectBag *bag,
                      gconstpointer key);

Lookup an object by key . If the key is currently reserved, the function will block until another thread commits or aborts the reservation. The caller owns the reference to the returned object. Use g_object_unref() to unreference it.

Parameters

bag

a CamelObjectBag

 

key

a key

 

Returns

the object corresponding to key , or NULL if not found.

[transfer full][nullable]


camel_object_bag_peek ()

gpointer
camel_object_bag_peek (CamelObjectBag *bag,
                       gconstpointer key);

Returns the object for key in bag , ignoring any reservations. If it isn't committed, then it isn't considered. This should only be used where reliable transactional-based state is not required.

Unlink other "peek" operations, the caller owns the returned object reference. Use g_object_unref() to unreference it.

Parameters

bag

a CamelObjectBag

 

key

an unreserved key

 

Returns

the object for key , or NULL if key is reserved or not found.

[transfer full][nullable]


camel_object_bag_reserve ()

gpointer
camel_object_bag_reserve (CamelObjectBag *bag,
                          gconstpointer key);

Reserves key in bag . If key is already reserved in another thread, then wait until the reservation has been committed.

After reserving key , you either get a reference to the object corresponding to key (similar to camel_object_bag_get()) or you get NULL, signifying that you MUST call either camel_object_bag_add() or camel_object_bag_abort().

Parameters

bag

a CamelObjectBag

 

key

the key to reserve

 

Returns

the object for key , or NULL if key is not found.

[transfer full][nullable]


camel_object_bag_add ()

void
camel_object_bag_add (CamelObjectBag *bag,
                      gconstpointer key,
                      gpointer object);

Adds object to bag . The key MUST have been previously reserved using camel_object_bag_reserve().

Parameters

bag

a CamelObjectBag

 

key

a reserved key

 

object

a GObject

 

camel_object_bag_abort ()

void
camel_object_bag_abort (CamelObjectBag *bag,
                        gconstpointer key);

Aborts a key reservation.

Parameters

bag

a CamelObjectBag

 

key

a reserved key

 

camel_object_bag_rekey ()

void
camel_object_bag_rekey (CamelObjectBag *bag,
                        gpointer object,
                        gconstpointer new_key);

Changes the key for object to new_key , atomically.

It is considered a programming error if object is not found in bag . In such case the function will emit a terminal warning and return.

Parameters

bag

a CamelObjectBag

 

object

a GObject

 

new_key

a new key for object

 

camel_object_bag_list ()

GPtrArray *
camel_object_bag_list (CamelObjectBag *bag);

Returns a GPtrArray of all the objects in the bag. The caller owns both the array and the object references, so to free the array use:

Parameters

bag

a CamelObjectBag

 

Returns

an array of objects in bag .

[element-type GObject][transfer full]


camel_object_bag_remove ()

void
camel_object_bag_remove (CamelObjectBag *bag,
                         gpointer object);

Removes object from bag .

Parameters

bag

a CamelObjectBag

 

object

a GObject

 

camel_object_bag_destroy ()

void
camel_object_bag_destroy (CamelObjectBag *bag);

Frees bag . As a precaution, the function will emit a warning to standard error and return without freeing bag if bag still has reserved keys.

Parameters

bag

a CamelObjectBag

 

Types and Values

CamelObjectBag

typedef struct _CamelObjectBag CamelObjectBag;