From c2bc03b0ee6048706ee180d084cf06d5383a0153 Mon Sep 17 00:00:00 2001
From: "Robert G. Jakabosky" <bobby@sharedrealm.com>
Date: Thu, 21 Apr 2011 06:05:15 -0700
Subject: [PATCH] Add zmq.poller object to API docs.

---
 API.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/API.md b/API.md
index b9ffb69..f15da79 100644
--- a/API.md
+++ b/API.md
@@ -175,3 +175,63 @@ See [zmq_msg_close(3)](http://api.zeromq.org/zmq_msg_close.html).
 
 	msg:close() -- free message contents and invalid `msg`
 
+# FD/ZMQ Socket poller object
+
+The poller object wraps [zmq_poll()](http://api.zeromq.org/zmq_poll.html) to allow polling
+of events from multiple ZMQ Sockets and/or normal sockets.
+
+## zmq.poller([pre_alloc])
+
+Construct a new poller object.  The optional `pre_alloc` parameter is to pre-size the poller
+for the number of sockets it will handle (the size can grow dynamically as-needed).
+
+	local poller = zmq.poller(64)
+
+## add(socket|fd, events, callback)
+
+Add a ZMQ Socket or fd to the poller.  `callback` will be called when one of the events
+in `events` is raised.
+
+	poller:add(sock, zmq.POLLIN, function(sock) print(sock, " is readable.") end)
+	poller:add(sock, zmq.POLLOUT, function(sock) print(sock, " is writable.") end)
+	poller:add(sock, zmq.POLLIN+zmq.POLLOUT, function(sock, revents)
+		print(sock, " has events:", revents)
+	end)
+
+## modify(socket|fd, events, callback)
+
+Change the `events` or `callback` for a socket/fd.
+
+	-- first wait for read event.
+	poller:add(sock, zmq.POLLIN, function(sock) print(sock, " is readable.") end)
+	-- now wait for write event.
+	poller:modify(sock, zmq.POLLOUT, function(sock) print(sock, " is writable.") end)
+
+## remove(socket|fd)
+
+Remove a socket/fd from the poller.
+
+	-- first wait for read event.
+	poller:add(sock, zmq.POLLIN, function(sock) print(sock, " is readable.") end)
+	-- remove socket from poller.
+	poller:remove(sock)
+
+## poll(timeout)
+
+Wait `timeout` microseconds for events on the registered sockets (timeout = -1, means
+wait indefinitely).  If any events happen, then those events are dispatched.
+
+	poller:poll(1000000) -- wait 1 second for events.
+
+## start()
+
+Start an event loop waiting for and dispatching events.
+
+	poller:start()
+
+## stop()
+
+Stop the event loop.
+
+	poller:stop()
+