docs: Added polling_echo example.

zmq.odin

@@ -33,6 +33,8 @@ foreign lib {
 
 	@(link_name = "zmq_recv")
 	_recv :: proc(s: Socket, buf: rawptr, len: c.size_t, flags: Flags) -> c.int ---
+	@(link_name = "zmq_poll")
+	_poll :: proc(items: rawptr, nitems: c.int, timeout: c.long) -> c.int ---
 	@(link_name = "zmq_strerror")
 	_strerror :: proc(errnum: c.int) -> cstring ---
 	@(link_name = "zmq_version")
@@ -55,14 +57,34 @@ Socket_Type :: enum c.int {
 }
 
 Flag :: enum c.int {
-	DONTWAIT = 1,
-	SNDMORE  = 2,
+	DONTWAIT,
+	SNDMORE,
 }
 
 Flags :: bit_set[Flag;c.int]
 
 NoBlock :: Flags{.DONTWAIT}
 
+// zmq_poll event flags (zmq.h ZMQ_POLLIN etc.). bit_set uses enum values as
+// bit indices, so these are positions (0..3), not the ZMQ_POLL* masks (1,2,4,8):
+// {.POLLIN} -> bit 0 -> mask 1 == ZMQ_POLLIN, {.POLLOUT} -> bit 1 -> mask 2, etc.
+Poll_Event :: enum c.short {
+	POLLIN  = 0,
+	POLLOUT = 1,
+	POLLERR = 2,
+	POLLPRI = 3,
+}
+Poll_Events :: bit_set[Poll_Event;c.short]
+
+// Mirrors C zmq_pollitem_t (16 B: ptr / int / short / short).
+// socket non-nil => poll the ØMQ socket; otherwise poll fd.
+Poll_Item :: struct {
+	socket:  Socket,
+	fd:      c.int,
+	events:  Poll_Events,
+	revents: Poll_Events,
+}
+
 Error :: union #shared_nil {
 	os.Platform_Error,
 	ZMQ_Error,
@@ -158,3 +180,12 @@ recv :: proc(s: Socket, buf: []u8, flags: Flags = Flags{}) -> (int, Error) {
 	return int(n), nil
 }
 
+// timeout_ms -1 = block forever, 0 = non-blocking.
+poll :: proc(items: []Poll_Item, timeout_ms: c.long) -> (int, Error) {
+	n := _poll(rawptr(&items[0]), c.int(len(items)), timeout_ms)
+	if n < 0 {
+		return -1, last_error()
+	}
+	return int(n), nil
+}
+