Package org.zeromq

Class ZPoller

java.lang.Object
org.zeromq.ZPoller
All Implemented Interfaces:
Closeable, AutoCloseable

public class ZPoller extends Object implements Closeable
Rewritten poller for ØMQ. Polls selectable channels and sockets for specified events.

This poller can be used in two ways:

  • the traditional one, where you make something like
     
                ZPoller poller = ...
                poller.register(socket, ZPoller.POLLIN);
                poller.register(channel, ZPoller.OUT);
    
                int events = poller.poll(-1L);
    
                if (poller.isReadable(socket)) {
                    ...
                }
                if (poller.writable(channel)) {
                    ...
                }
    
    
  • the event-driven way
     
    
                ZPoller poller = ...
    
                poller.setGlobalHandler(...)
                ZPoller.EventsHandler handler = ...
    
                // The events method of the handler will be called
                poller.register(channel, handler, ZPoller.IN);
    
                // The events method of the global handler will be called
                poller.register(socket, ZPoller.POLLOUT);
    
                poller.poll(-1L);
                // handlers have been called
    
    
The motivations of this rewriting are:
  • the bare poller used ZMQ.poll(Selector, PollItem[], int, long). This method did not allow to choose the selector used for polling, relying on a ThreadLocal, which is dangerous.
  • the bare poller use algorithms tailored for languages with manual allocation. No need here as Java allows more flexibility. TODO There still may be a small penalty cost.
  • Field Details

  • Constructor Details

    • ZPoller

      public ZPoller(ZPoller poller)
      Creates a new poller based on the current one. This will be a shadow poller, sharing the same selector and items creator. The global events handler will not be shared.
      Parameters:
      poller - the main poller.
    • ZPoller

      public ZPoller(Selector selector)
      Creates a new poller with a given selector for operational polling.
      Parameters:
      selector - the selector to use for polling.
    • ZPoller

      public ZPoller(ZContext context)
      Creates a new poller attached to a given context that will provide selector for operational polling.
      Parameters:
      context - the context that will provide the selector to use for polling.
    • ZPoller

      public ZPoller(ZPoller.ItemCreator creator, ZPoller poller)
      Creates a new poller based on the current one. This will be a shadow poller, sharing the same selector. The global events handler will not be shared.
      Parameters:
      creator - the items creator
      poller - the main poller.
    • ZPoller

      public ZPoller(ZPoller.ItemCreator creator, ZContext context)
      Creates a new poller attached to a given context that will provide selector for operational polling.
      Parameters:
      creator - the items creator
      context - the context that will provide the selector to use for polling.
    • ZPoller

      public ZPoller(ZPoller.ItemCreator creator, Selector selector)
      Creates a new poller.
      Parameters:
      creator - the items creator
      selector - the selector to use for polling.
    • ZPoller

      private ZPoller(ZPoller.ItemCreator creator, ZContext context, Selector selector)
      Creates a new poller.
      Parameters:
      creator - the items creator
      context - the optional context where the selector should come from. If non-null, the selector will be destroyed on close.
      selector - the selector to use for polling.
  • Method Details

    • create

      protected ZPoller.ItemHolder create(ZMQ.Socket socket, ZPoller.EventsHandler handler, int events)
    • create

      protected ZPoller.ItemHolder create(SelectableChannel channel, ZPoller.EventsHandler handler, int events)
    • setGlobalHandler

      public void setGlobalHandler(ZPoller.EventsHandler globalHandler)
      Sets the global events handler for all registered sockets.
      Parameters:
      globalHandler - the events handler to set
    • getGlobalHandler

      public ZPoller.EventsHandler getGlobalHandler()
      Returns the global events handler for all registered sockets.
      Returns:
      the global events handler for all registered sockets.
    • register

      public final boolean register(ZMQ.Socket socket, BiFunction<ZMQ.Socket,Integer,Boolean> handler, int events)
      Register a Socket for polling on specified events.
      Parameters:
      socket - the registering socket.
      handler - the events handler for this socket
      events - the events to listen to, as a mask composed by ORing POLLIN, POLLOUT and POLLERR.
      Returns:
      true if registered, otherwise false
    • register

      public final boolean register(ZMQ.Socket socket, ZPoller.EventsHandler handler, int events)
      Register a Socket for polling on specified events.
      Parameters:
      socket - the registering socket.
      handler - the events handler for this socket
      events - the events to listen to, as a mask composed by ORing POLLIN, POLLOUT and POLLERR.
      Returns:
      true if registered, otherwise false
    • register

      public final boolean register(ZMQ.Socket socket, ZPoller.EventsHandler handler)
    • register

      public final boolean register(ZMQ.Socket socket, int events)
    • register

      public final boolean register(SelectableChannel channel, BiFunction<SelectableChannel,Integer,Boolean> handler, int events)
      Registers a SelectableChannel for polling on specified events.
      Parameters:
      channel - the registering channel.
      handler - the events handler for this channel
      events - the events to listen to, as a mask composed by ORing POLLIN, POLLOUT and POLLERR.
      Returns:
      true if registered, otherwise false
    • register

      public final boolean register(SelectableChannel channel, ZPoller.EventsHandler handler, int events)
      Registers a SelectableChannel for polling on specified events.
      Parameters:
      channel - the registering channel.
      handler - the events handler for this channel
      events - the events to listen to, as a mask composed by ORing POLLIN, POLLOUT and POLLERR.
      Returns:
      true if registered, otherwise false
    • register

      public final boolean register(SelectableChannel channel, ZPoller.EventsHandler handler)
      Registers a SelectableChannel for polling on all events.
      Parameters:
      channel - the registering channel.
      handler - the events handler for this channel
      Returns:
      true if registered, otherwise false
    • register

      public final boolean register(SelectableChannel channel, int events)
      Registers a SelectableChannel for polling on specified events.
      Parameters:
      channel - the registering channel.
      events - the events to listen to, as a mask composed by ORing POLLIN, POLLOUT and POLLERR.
      Returns:
      true if registered, otherwise false
    • register

      public final boolean register(ZPoller.ItemHolder item)
      Register an ItemHolder for polling on specified events.
      Parameters:
      item - the registering item.
      Returns:
      true if registered, otherwise false
    • unregister

      public final boolean unregister(Object socketOrChannel)
      Unregister a Socket or SelectableChannel for polling on the specified events.
      Parameters:
      socketOrChannel - the Socket or SelectableChannel to be unregistered
      Returns:
      true if unregistered, otherwise false TODO would it be useful to unregister only for specific events ?
    • poll

      public int poll(long timeout)
      Issue a poll call, using the specified timeout value.

      Since ZeroMQ 3.0, the timeout parameter is in milliseconds, but prior to this the unit was microseconds.

      Parameters:
      timeout - the timeout, as per zmq_poll (); if -1, it will block indefinitely until an event happens; if 0, it will return immediately; otherwise, it will wait for at most that many milliseconds/microseconds (see above).
      Returns:
      how many objects where signaled by poll ()
      See Also:
      • "http://api.zeromq.org/3-0:zmq-poll"
    • poll

      protected int poll(long timeout, boolean dispatchEvents)
      Issue a poll call, using the specified timeout value.
      Parameters:
      timeout - the timeout, as per zmq_poll ();
      dispatchEvents - true to dispatch events using items handler and the global one.
      Returns:
      how many objects where signaled by poll ()
      See Also:
      • "http://api.zeromq.org/3-0:zmq-poll"
    • dispatch

      private boolean dispatch(Set<ZPoller.CompositePollItem> all, int size)
    • poll

      protected int poll(Selector selector, long tout, Collection<PollItem> items)
    • dispatch

      protected boolean dispatch(Collection<? extends ZPoller.ItemHolder> all, int size)
      Dispatches the polled events.
      Parameters:
      all - the items used for dispatching
      size - the number of items to dispatch
      Returns:
      true if correctly dispatched, false in case of error
    • dispatch

      public boolean dispatch()
    • isReadable

      public boolean isReadable(SelectableChannel channel)
      Tells if a channel is readable from this poller.
      Parameters:
      channel - the channel to ask for.
      Returns:
      true if readable, otherwise false
    • readable

      public boolean readable(SelectableChannel channel)
    • isReadable

      public boolean isReadable(ZMQ.Socket socket)
      Tells if a socket is readable from this poller.
      Parameters:
      socket - the socket to ask for.
      Returns:
      true if readable, otherwise false
    • readable

      public boolean readable(ZMQ.Socket socket)
    • readable

      public boolean readable(Object socketOrChannel)
    • pollin

      public boolean pollin(ZMQ.Socket socket)
    • pollin

      public boolean pollin(SelectableChannel channel)
    • isWritable

      public boolean isWritable(SelectableChannel channel)
      Tells if a channel is writable from this poller.
      Parameters:
      channel - the channel to ask for.
      Returns:
      true if writable, otherwise false
    • writable

      public boolean writable(SelectableChannel channel)
    • isWritable

      public boolean isWritable(ZMQ.Socket socket)
      Tells if a socket is writable from this poller.
      Parameters:
      socket - the socket to ask for.
      Returns:
      true if writable, otherwise false
    • writable

      public boolean writable(ZMQ.Socket socket)
    • writable

      public boolean writable(Object socketOrChannel)
    • pollout

      public boolean pollout(ZMQ.Socket socket)
    • pollout

      public boolean pollout(SelectableChannel channel)
    • isError

      public boolean isError(SelectableChannel channel)
      Tells if a channel is in error from this poller.
      Parameters:
      channel - the channel to ask for.
      Returns:
      true if in error, otherwise false
    • error

      public boolean error(SelectableChannel channel)
    • isError

      public boolean isError(ZMQ.Socket socket)
      Tells if a socket is in error from this poller.
      Parameters:
      socket - the socket to ask for.
      Returns:
      true if in error, otherwise false
    • error

      public boolean error(ZMQ.Socket socket)
    • error

      public boolean error(Object socketOrChannel)
    • pollerr

      public boolean pollerr(ZMQ.Socket socket)
    • pollerr

      public boolean pollerr(SelectableChannel channel)
    • close

      public void close() throws IOException
      Destroys the poller. Does actually nothing.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException
    • destroy

      public void destroy()
      Destroys the poller without exception.
    • add

      protected boolean add(Object socketOrChannel, ZPoller.ItemHolder holder)
    • createContainer

      @Deprecated protected Set<ZPoller.ItemHolder> createContainer(int size)
      Deprecated.
    • items

      protected Collection<? extends ZPoller.ItemHolder> items()
    • items

      protected Iterable<ZPoller.ItemHolder> items(Object socketOrChannel)
    • filter

      protected PollItem filter(Object socketOrChannel, int events)