camel-object-bag: Camel Reference Manual

## camel-object-bag camel-object-bag |

## Functions

gpointer | (*CamelCopyFunc) ()
CamelObjectBag * | camel_object_bag_new ()
gpointer | camel_object_bag_get ()
gpointer | camel_object_bag_peek ()
gpointer | camel_object_bag_reserve ()
void | camel_object_bag_add ()
void | camel_object_bag_abort ()
void | camel_object_bag_rekey ()
GPtrArray * | camel_object_bag_list ()
void | camel_object_bag_remove ()
void | camel_object_bag_destroy ()

## Types and Values

| CamelObjectBag

## 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.

[skip]

#### 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:

        g_ptr_array_foreach (array, (GFunc) g_object_unref, NULL);
        g_ptr_array_free (array, TRUE);

#### 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;