Function wyrd_add_property_callback

Function Documentation

wyrd_error_t wyrd_add_property_callback(struct wyrd_handle *handle, char const *path, wyrd_property_callback callback, void *baton)

Set observation callbacks for properties.

Callbacks get invoked when the property changes. The baton you provide when setting a callback is passed to the callback as the final parameter. Note that these functions do not take ownership of any data; the caller must take care to scope lifetime appropriately.

Generally speaking, the tuple of path, callback and baton is treated as unique. However, due to the way these callbacks may be integrated to hook into other event/signalling frameworks, the add(set) operation increments an internal reference counter on that tuple. Likewise, the remove operation decrements the reference count. By contrast, the clear operation removes the tuple completely.

This effectively yields two modes of operation: using add/remove you make use of the reference counting. Using add/clear, operations effectively act as idempotent.

As a final note, callbacks may be invoked on threads other than the main thread. They should terminate relatively quickly as not to block background threads, and access data in a thread-safe manner.

Parameters

  • handle – [in] A handle to an opened resource.

  • path – [in] The path to the property to observe.

  • callback – [in] A wyrd_property_callback provided by the user.

  • baton – [in] An opaque pointer that will be handled to callback if it gets invoked.

Return values

  • WYRD_ERR_SUCCESS – On success.

  • WYRD_ERR_INVALID_VALUE – If any of the parameters are invalid, such as e.g. NULL when they should not be, etc.