Listeners

Listeners are used to monitor events that represent changes to the tuples stored in a space.

Listeners are callback-driven, unlike space EventBrowsers, where the user decides when to get the next event by invoking the EventBrowser’s next method. This means that a method of a callback class (or a callback function in C) provided by the user will be automatically invoked by the ActiveSpaces library code whenever a change happens to one of the tuples in the space being monitored.

In Java, to use a listener, users provide a class to the listen method that implements one or more of the listeners interfaces.

• The PutListener interface requires a onPut(PutEvent event) method.
• The TakeListener interface requires a onTake(TakeEvent event) method.
• The ExpireListener interface requires a onExpire(ExpireEvent event) method.
• The SeedListener interface requires a onSeed(SeedEvent event) method.
• The UnseedListener interface requires a onUnseed(UnseedEvent event) method.

In C, users provide a callback function to the tibasListener_Create function or one of the additional listener creation functions that will be invoked for all event types. This user callback function will be passed a single tibas_spaceEvent object that they can pass to the tibasSpaceEvent_GetType function to determine the type of the event.

• SpaceEvents of type TIBAS_EVENT_PUT are generated whenever a tuple is inserted, overwritten or updated.
• SpaceEvents of type TIBAS_EVENT_TAKE are generated whenever a tuple is taken or removed.
• SpaceEvents of type TIBAS_EVENT_EXPIRE are generated whenever a tuple reaches the end of its time to live and expires from the space.
• SpaceEvents of type TIBAS_EVENT_SEED are generated whenever there is redistribution after a seeder leaves the space and the local node is now seeding additional tuples. This is only applicable if the listener distribution scope is SEEDED.
• SpaceEvents of type TIBAS_EVENT_UNSEED are generated whenever there is redistribution after a seeder joins the space and the local node is no longer seeding some of the tuples. Only applicable if the listener distribution scope is SEEDED.

You can optionally specify a filter string when creating a listener. A filtered listener will only return events that match the specified filter. This is done by adding a filter argument when you invoke the listen() method on the metaspace. The filter argument contains a string in the language described in Filters. Some of the filtering may be executed in a distributed manner by ActiveSpaces in order to optimize performance.

In addition to the basic tibasListenerCreate() function, the C API provides functions that allow you to create additional types of listener:

tibasSpaceMemberListener_Create()

—Creates a space member listener.

tibasMemberListener_Create()

—Creates a member event listener.

tibasSpaceRemoteMemberListener_Create()

—Creates a remote space member listener.

tibasRemoteMemberListener_Create()

—Creates a remote member listener.

tibasSpaceStateListener_Create()

—Creates a space state listener.

tibasSpaceDefListener_Create()

—Creates a space definition listener.

A listener can have either time scope or distribution scope, defined by setting the values of fields in the listener’s ListenerDef object:

Time scope

 The time scope can be used to narrow down the period of time of interest.

• snapshot means that the listener contains only PUT events corresponding to the tuples stored in the space at creation time.
• new means that the listener starts empty and is updated only with events related to new or overridden tuples in the space. This is the default Time scope of ListenerDef.
• new events means that the listener starts empty, and is updated with all events that occur in the space after creation time. Unlike the time scope new, this time scope includes events (such as TAKE or EXPIRE events) related to tuples already contained in the space at creation time.
• all means that the listener starts with all the tuples currently in the space at creation time (which will be presented as an initial set of PUT events) and then is continuously updated according to changes in the space.

Distribution scope

 The distribution scope can be used to narrow down the set of tuples or events being browsed.

• all is used to listen to events related to all tuples in the space. This is the default value of the Distribution scope.
• seeded is used to listen only to events associated with the tuples in the space that are seeded by this member. It will be empty unless the member is a seeder on the space.

When the listener’s distribution scope is set to seeded, two additional types of events may be generated:

SEED

 Generated when the member that created the listener starts seeding an tuple.

UNSEED

 Generated when the member that created the listener no longer seeds an tuple.

For a description of the ASListener example program, which illustrates how to set up a listener, see ASListener.