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)