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 0MQ. 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 use this method who does 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ZPoller.EventsHandler
static interface	ZPoller.ItemCreator
static interface	ZPoller.ItemHolder
static class	ZPoller.ZPollItem

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERR
static int	IN
static int	OUT
static int	POLLERR
static int	POLLIN These values can be ORed to specify what we want to poll for.
static int	POLLOUT

Constructor Summary

Constructors

Constructor and Description
ZPoller(Selector selector) Creates a new poller with a given selector for operational polling.
ZPoller(ZPoller.ItemCreator creator, Selector selector) Creates a new poller.
ZPoller(ZPoller.ItemCreator creator, ZPoller poller) Creates a new poller based on the current one.
ZPoller(ZPoller poller) Creates a new poller based on the current one.

Method Summary

Methods

Modifier and Type	Method and Description
protected boolean	add(Object socketOrChannel, ZPoller.ItemHolder holder)
void	close() Destroys the poller.
protected ZPoller.ItemHolder	create(SelectableChannel channel, ZPoller.EventsHandler handler, int events)
protected ZPoller.ItemHolder	create(ZMQ.Socket socket, ZPoller.EventsHandler handler, int events)
protected Set<ZPoller.ItemHolder>	createContainer(int size)
void	destroy() Destroys the poller and the associated selector without exception.
boolean	dispatch()
protected boolean	dispatch(Collection<ZPoller.ItemHolder> all, int size) Dispatches the polled events.
boolean	error(Object socketOrChannel)
boolean	error(SelectableChannel channel)
boolean	error(ZMQ.Socket socket)
protected PollItem	filter(Object socketOrChannel, int events)
ZPoller.EventsHandler	getGlobalHandler() Returns the global events handler for all registered sockets.
boolean	isError(SelectableChannel channel) Tells if a channel is in error from this poller.
boolean	isError(ZMQ.Socket socket) Tells if a socket is in error from this poller.
boolean	isReadable(SelectableChannel channel) Tells if a channel is readable from this poller.
boolean	isReadable(ZMQ.Socket socket) Tells if a socket is readable from this poller.
boolean	isWritable(SelectableChannel channel) Tells if a channel is writable from this poller.
boolean	isWritable(ZMQ.Socket socket) Tells if a socket is writable from this poller.
protected Collection<ZPoller.ItemHolder>	items()
protected Iterable<ZPoller.ItemHolder>	items(Object socketOrChannel)
int	poll(long timeout) Issue a poll call, using the specified timeout value.
protected int	poll(long timeout, boolean dispatchEvents) Issue a poll call, using the specified timeout value.
protected int	poll(Selector selector, long tout, Collection<PollItem> items)
boolean	readable(Object socketOrChannel)
boolean	readable(SelectableChannel channel)
boolean	readable(ZMQ.Socket socket)
boolean	register(SelectableChannel channel, int events)
boolean	register(SelectableChannel channel, ZPoller.EventsHandler handler)
boolean	register(SelectableChannel channel, ZPoller.EventsHandler handler, int events) Register a SelectableChannel for polling on specified events.
boolean	register(ZMQ.Socket socket, int events)
boolean	register(ZMQ.Socket socket, ZPoller.EventsHandler handler)
boolean	register(ZMQ.Socket socket, ZPoller.EventsHandler handler, int events) Register a Socket for polling on specified events.
boolean	register(ZPoller.ItemHolder item) Register an ItemHolder for polling on specified events.
void	setGlobalHandler(ZPoller.EventsHandler globalHandler) Sets the global events handler for all registered sockets.
boolean	unregister(Object socketOrChannel) Unregister a Socket or SelectableChannel for polling on the specified events.
boolean	writable(Object socketOrChannel)
boolean	writable(SelectableChannel channel)
boolean	writable(ZMQ.Socket socket)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POLLIN

public static final int POLLIN

These values can be ORed to specify what we want to poll for.

See Also:

Constant Field Values

POLLOUT

public static final int POLLOUT

See Also:

Constant Field Values

POLLERR

public static final int POLLERR

See Also:

Constant Field Values

IN

public static final int IN

See Also:

Constant Field Values

OUT

public static final int OUT

See Also:

Constant Field Values

ERR

public static final int ERR

See Also:

Constant Field Values

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(Selector selector)

Creates a new poller with a given selector for operational polling.

Parameters:

selector - 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,
       Selector selector)

Creates a new poller.

Parameters:

creator - the items creator

selector - the selector to use for polling.

Method Detail

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,
               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,
               ZPoller.EventsHandler handler,
               int events)

Register a SelectableChannel for polling on specified events.

Parameters:

channel - the registering channel.

handler - the events handler for this socket

events - the events to listen to, as a mask composed by XORing POLLIN, POLLOUT and POLLERR.

Returns:

true if registered, otherwise false

register

public final boolean register(SelectableChannel channel,
               ZPoller.EventsHandler handler)

register

public final boolean register(SelectableChannel channel,
               int events)

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"

poll

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

dispatch

protected boolean dispatch(Collection<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)

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)

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)

close

public void close()
           throws IOException

Destroys the poller. Does actually nothing.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

destroy

public void destroy()

Destroys the poller and the associated selector without exception.

add

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

createContainer

protected Set<ZPoller.ItemHolder> createContainer(int size)

items

protected Collection<ZPoller.ItemHolder> items()

items

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

filter

protected PollItem filter(Object socketOrChannel,
              int events)