tibasListener_Create()

Creates a listener object and associates a specified callback function with it.

Declaration

tibas_status tibasListener_Create(
    tibasListener* listener,
    tibas_onEvent  callback,
    void*          closure)

Parameters

Parameter Description
listener The new listener object that is returned.
callback The name of the callback function.
closure Pointer to closure data that will be passed to the callback function when the listener is invoked.

Remarks

Use the tibasListenerCreate() function to create a listener object and associate a callback function with it.

The callback function that you specify with the callback parameter is called when you attach the listener to a metaspace on which you want to listen for events by calling the tibasMetaspace_Listen()function or the tibasSpace_Listen() function.

When you call tibasListenerCreate(), a listener object is created. the listener is then activated using the tibasMetaspace_Listen() or tibasSpace_Listen() functions. The callback function is passed a tibasSpaceEvent object whose type can be determined by invoking the tibasSpaceEvent_GetType function.

The callback function that you provide must be able to process all types of space events generated by ActiveSpaces:

  • TIBAS_EVENT_PUT when a tuple is inserted, overwritten, or updated.
  • TIBAS_EVENT_TAKE when a tuple is taken or removed.
  • TIBAS_EVENT_EXPIRE when a tuple reaches the end of its time to live and expires from the space
  • TIBAS_EVENT_SEED are when there is redistribution after a seeder joins or leaves, and the local node is seeding or unseeding. This is only applicable if the listener distribution scope is SEEDED.
  • TIBAS_EVENT_UNSEED when there is redistribution after a seeder joins or leaves, and the local node is seeding or unseeding. This is only applicable if the listener distribution scope is SEEDED.

You can also specify that a current snapshot of the entries stored in the space (sometimes referred to as initial values) is prepended to the stream of events. In this case, the initial values of all the tuples contained in the space at the listener’s creation time are seen as space events of type PUT preceding the current stream of events.

The tibasListener object returned by tibasListener_Create() is required input for the tibasMetaspace_Listen() function.

The closure argument is a pointer to closure data that is passed to the callback function when the listener is invoked. If you do not want to pass closure data to the callback function, specify NULL for this argument.

See Also

tibasMetaspace_Listen(), tibasSpace_Listen(),