cztop 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1619d296889181d095f1d88cf2fbf9b3f1d99f9c
-  data.tar.gz: c85c0ac08700a9f7558a9936acf8397688138248
+  metadata.gz: a2f6944c31fc9ad2963801d45a819492a0c4a82c
+  data.tar.gz: cf4cacb4b356309058278b871143fb22c1ba53fa
 SHA512:
-  metadata.gz: 65d9cac510d5e66ae019827bd87c3959362f3e9a5ff5e4579864a2a56e5bfaef7b9de7e9b072e26c6862130b7e0b22f86c93a9f5cf0b498004c68fe1e140fc80
-  data.tar.gz: 371faea1cc8ccdb339033a2db20960cddfa9c5e40d59db4841013a06d3a72c0e70ccfe63b7e478724f46e4a963b956f045d52257f8e88787c38cbd588a836a1d
+  metadata.gz: 49e3cfd581c7424139a818450aa46b063a244610e96ef488371e2e70583a595b57e5c373799b58ac42c291f92e9c5bacb83f8f26fadf7363a2c6dd05e24ef775
+  data.tar.gz: a3cf1ea8a5b50b522eb0c7a7505c11fd068100fead2cd141410f9ae5dfb64f69f8a79f5ba3008dcd62b46ae95f258a5b1db30901188916ee863bd0e99198e717

data/CHANGES.md

@@ -1,3 +1,21 @@
+0.4.0 (13/04/2016)
+-----
+* CZTop::Poller learns the following methods for convenience and compatibility:
+  * #add_reader
+  * #add_writer
+  * #remove_reader
+  * #remove_writer
+* CZTop::Poller::Aggregated gets method delegators for the following 8 methods
+  for compatibility:
+  * CZTop::Poller#add
+  * CZTop::Poller#add_reader
+  * CZTop::Poller#add_writer
+  * CZTop::Poller#modify
+  * CZTop::Poller#remove
+  * CZTop::Poller#remove_reader
+  * CZTop::Poller#remove_writer
+  * CZTop::Poller#sockets
+
 0.3.0 (13/04/2016)
 -----
 * port CZTop::Poller to zmq_poller_*() functions so it supports thread-safe

data/lib/cztop/poller.rb

@@ -1,12 +1,12 @@
 module CZTop
   # A non-trivial socket poller.
   #
-  # It can poll for reading and writing, and supports thread-safe sockets
-  # (SERVER/CLIENT/RADIO/DISH).
+  # It can poll for readability and writability, and supports thread-safe
+  # sockets (SERVER/CLIENT/RADIO/DISH).
   #
   # This implementation is NOT based on CZMQ's +zpoller+. Reasons:
   #
-  # * +zpoller+ can only poll for reading
+  # * +zpoller+ can only poll for readability
   #
   class Poller
     include ::CZMQ::FFI
@@ -23,22 +23,36 @@ module CZTop
           ZMQ.poller_destroy(ptr_ptr)
         end)
       @event_ptr = FFI::MemoryPointer.new(ZMQ::PollerEvent)
-      readers.each { |r| add(r) }
+      readers.each { |r| add_reader(r) }
     end
 
-    # Adds a socket to be polled for reading.
+    # Adds a socket to be polled for readability.
     # @param socket [Socket, Actor] the socket
-    # @param events [Integer] events you're interested in (see constants in
-    #   {ZMQ}
+    # @param events [Integer] bitwise-OR'd events you're interested in (see
+    #   POLLIN and POLLOUT constants in {CZTop::Poller::ZMQ}
     # @return [void]
     # @raise [ArgumentError] if it's not a socket
-    def add(socket, events = ZMQ::POLLIN)
+    def add(socket, events)
       ptr = ptr_for_socket(socket)
       rc = ZMQ.poller_add(@poller_ptr, ptr, nil, events)
       HasFFIDelegate.raise_zmq_err if rc == -1
       remember_socket(socket, events)
     end
 
+    # Convenience method to register a socket for readability. See {#add}.
+    # @param socket [Socket, Actor] the socket
+    # @return [void]
+    def add_reader(socket)
+      add(socket, ZMQ::POLLIN)
+    end
+
+    # Convenience method to register a socket for writability. See {#add}.
+    # @param socket [Socket, Actor] the socket
+    # @return [void]
+    def add_writer(socket)
+      add(socket, ZMQ::POLLOUT)
+    end
+
     # Modifies the events of interest for the given socket.
     # @param socket [Socket, Actor] the socket
     # @param events [Integer] events you're interested in (see constants in
@@ -64,6 +78,32 @@ module CZTop
       forget_socket(socket)
     end
 
+    # Removes a reader socket that was registered for readability only.
+    #
+    # @param socket [Socket, Actor] the socket
+    # @raise [ArgumentError] if it's not registered, not registered for
+    #   readability, or registered for more than just readability
+    def remove_reader(socket)
+      if event_mask_for_socket(socket) == ZMQ::POLLIN
+        remove(socket)
+        return
+      end
+      raise ArgumentError, "not registered for readability only: %p" % socket
+    end
+
+    # Removes a reader socket that was registered for writability only.
+    #
+    # @param socket [Socket, Actor] the socket
+    # @raise [ArgumentError] if it's not registered, not registered for
+    #   writability, or registered for more than just writability
+    def remove_writer(socket)
+      if event_mask_for_socket(socket) == ZMQ::POLLOUT
+        remove(socket)
+        return
+      end
+      raise ArgumentError, "not registered for writability only: %p" % socket
+    end
+
     # Waits for registered sockets to become readable or writable, depending
     # on what you're interested in.
     #
@@ -98,13 +138,10 @@ module CZTop
 
     # @param ptr [FFI::Pointer] pointer to the socket
     # @return [Socket, Actor] socket corresponding to given pointer
+    # @raise [ArgumentError] if pointer is not known
     def socket_for_ptr(ptr)
       @sockets[ptr.to_i] or
-        # NOTE: This should never happen, since #wait will return nil if
-        # +zpoller_wait+ returned NULL. But it's better to fail early in case
-        # it ever returns a wrong pointer.
-        HasFFIDelegate.raise_zmq_err(
-          "no socket known for pointer #{ptr.inspect}")
+        raise ArgumentError, "no socket known for pointer %p" % ptr
     end
 
     # @return [Array<CZTop::Socket>] all sockets registered with this poller
@@ -113,9 +150,13 @@ module CZTop
       @sockets.values
     end
 
+    # Returns the event mask for the given, registered socket.
+    # @param socket [Socket, Actor] which socket's events to return
+    # @return [Integer] event mask for the given socket
+    # @raise [ArgumentError] if socket is not registered
     def event_mask_for_socket(socket)
       @events[socket] or
-        raise "no event mask known for socket %p" % socket
+        raise ArgumentError, "no event mask known for socket %p" % socket
     end
 
     private
@@ -128,11 +169,16 @@ module CZTop
       Zsock.resolve(socket)
     end
 
+    # Keeps a reference to the given socket, and remembers its event mask.
+    # @param socket [Socket, Actor] the socket
+    # @param events [Integer] the event mask
     def remember_socket(socket, events)
       @sockets[ptr_for_socket(socket).to_i] = socket
       @events[socket] = events
     end
 
+    # Discards the referencel to the given socket, and forgets its event mask.
+    # @param socket [Socket, Actor] the socket
     def forget_socket(socket)
       @sockets.delete(ptr_for_socket(socket).to_i)
       @events.delete(socket)
@@ -182,9 +228,24 @@ module CZTop
   # getting an array of readable/writable sockets:
   #
   # * in {#wait}, poll with given timeout
-  # * in case there was an event, poll again with zero timeout until no more
-  #   sockets
-  # * accumulate results into two lists
+  # * in case there was an event:
+  #   * deregister the corresponding event(s) on the registered socket
+  #   * poll again with zero timeout until no more sockets
+  #   * repeat and accumulate results into two lists
+  #
+  # = Forwarded Methods
+  #
+  # The following methods are defined on this class too, and calls are
+  # forwarded directly to the actual {CZTop::Poller} instance:
+  #
+  # * {CZTop::Poller#add}
+  # * {CZTop::Poller#add_reader}
+  # * {CZTop::Poller#add_writer}
+  # * {CZTop::Poller#modify}
+  # * {CZTop::Poller#remove}
+  # * {CZTop::Poller#remove_reader}
+  # * {CZTop::Poller#remove_writer}
+  # * {CZTop::Poller#sockets}
   #
   class Poller::Aggregated
 
@@ -197,6 +258,17 @@ module CZTop
     # @return [Array<CZTop::Socket>] writable sockets
     attr_reader :writables
 
+    extend Forwardable
+    def_delegators :@poller,
+      :add,
+      :add_reader,
+      :add_writer,
+      :modify,
+      :remove,
+      :remove_reader,
+      :remove_writer,
+      :sockets
+
     # Initializes the aggregated poller.
     # @param poller [CZTop::Poller] the wrapped poller
     def initialize(poller = CZTop::Poller.new)
@@ -263,9 +335,7 @@ module CZTop
     # were before the call to {#wait}.
     # @return [void]
     def restore_event_masks
-      @event_masks.each do |socket, mask|
-        poller.modify(socket, mask)
-      end
+      @event_masks.each { |socket, mask| poller.modify(socket, mask) }
     end
   end
 
@@ -333,7 +403,7 @@ module CZTop
   end
 
   # This is the trivial poller based on zpoller. It only supports polling
-  # for reading, but it also supports doing that on CLIENT/SERVER sockets,
+  # for readability, but it also supports doing that on CLIENT/SERVER sockets,
   # which is useful for {CZTop::Poller}.
   #
   # @see http://api.zeromq.org/czmq3-0:zpoller

data/lib/cztop/version.rb

@@ -1,3 +1,3 @@
 module CZTop
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cztop
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrik Wenger