Package org.zeromq

Class ZPoller

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

    public class ZPoller
    extends java.lang.Object
    implements java.io.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.
    • Constructor Detail

      • 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​(java.nio.channels.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,
                       java.nio.channels.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,
                        java.nio.channels.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 Detail

      • 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,​java.lang.Integer,​java.lang.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,
                                      int events)
      • register

        public final boolean register​(java.nio.channels.SelectableChannel channel,
                                      BiFunction<java.nio.channels.SelectableChannel,​java.lang.Integer,​java.lang.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​(java.nio.channels.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​(java.nio.channels.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​(java.nio.channels.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​(java.lang.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"
      • poll

        protected int poll​(java.nio.channels.Selector selector,
                           long tout,
                           java.util.Collection<PollItem> items)
      • dispatch

        protected boolean dispatch​(java.util.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​(java.nio.channels.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​(java.nio.channels.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​(java.lang.Object socketOrChannel)
      • pollin

        public boolean pollin​(ZMQ.Socket socket)
      • pollin

        public boolean pollin​(java.nio.channels.SelectableChannel channel)
      • isWritable

        public boolean isWritable​(java.nio.channels.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​(java.nio.channels.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​(java.lang.Object socketOrChannel)
      • pollout

        public boolean pollout​(ZMQ.Socket socket)
      • pollout

        public boolean pollout​(java.nio.channels.SelectableChannel channel)
      • isError

        public boolean isError​(java.nio.channels.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​(java.nio.channels.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​(java.lang.Object socketOrChannel)
      • pollerr

        public boolean pollerr​(ZMQ.Socket socket)
      • pollerr

        public boolean pollerr​(java.nio.channels.SelectableChannel channel)
      • close

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

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

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

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

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

        protected PollItem filter​(java.lang.Object socketOrChannel,
                                  int events)