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)