Distributed Events

Hazelcast allows you to register for entry events to get notified when events occurred. Event Listeners are cluster-wide so when a listener is registered in one member of cluster, it is actually registering for events originated at any member in the cluster. When a new member joins, events originated at the new member will also be delivered.

An Event is created only if there is a listener registered. If there is no listener registered, then no event will be created. If a predicate provided while registering the listener, predicate should be passed before sending the event to the listener (node/client).

As a rule of thumb, event listener should not implement heavy processes in its event methods which block the thread for long time. If needed, ExecutorService can be used to transfer long running processes to another thread and offload current listener thread.

Event Listeners

• MembershipListener for cluster membership events
• DistributedObjectListener for distributed object creation and destroy events
• MigrationListener for partition migration start and complete events
• LifecycleListener for HazelcastInstance lifecycle events
• EntryListener for IMap and MultiMap entry events
• ItemListener for IQueue, ISet and IList item events (please refer to Event Registration and Configuration sections of Set and List).
• MessageListener for ITopic message events
• ClientListener for client connection events

Global Event Configuration

• hazelcast.event.queue.capacity: default value is 1000000
• hazelcast.event.queue.timeout.millis: default value is 250
• hazelcast.event.thread.count: default value is 5

There is a striped executor in each node to control and dispatch received events to user. This striped executor also guarantees the order. For all events in Hazelcast, the order that events are generated and the order they are published to the user are guaranteed for given keys. For map and multimap, order is preserved for the operations on same key of the entry. For list, set, topic and queue, order is preserved for events on that instance of the distributed data structure.

Order guarantee is achieved by making only one thread responsible for a particular set of events (entry events of a key in a map, item events of a collection, etc.) in StripedExecutor.

If event queue reaches the capacity (hazelcast.event.queue.capacity) and last item cannot be put to the event queue for the period specified in hazelcast.event.queue.timeout.millis, these events will be dropped with a warning message like "EventQueue overloaded".

If listeners are doing a computation that requires a long time, this can cause event queue to reach its maximum capacity and lost of events. For map and multimap, hazelcast.event.thread.count can be configured to a higher value so that less collision occurs for keys, therefore worker threads will not block each other in StripedExecutor. For list, set, topic and queue, heavy work should be offloaded to another thread. Notice that, in order to preserve order guarantee, the user should implement similar logic with StripedExecutor in offloaded thread pool.

RELATED INFORMATION

Please refer to Listener Configurations section on how to configure each listener.