ffi-rxs 1.0.0 → 1.0.1

data/lib/ffi-rxs/message.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 module XS
 
@@ -28,71 +29,76 @@ module XS
   # When you are done using a *received* message object, call #close to
   # release the associated buffers.
   #
-  #  received_message = Message.create
-  #  if received_message
-  #    rc = socket.recvmsg(received_message)
-  #    if XS::Util.resultcode_ok?(rc)
-  #      puts "Message contained: #{received_message.copy_out_string}"
-  #    else
-  #      STDERR.puts "Error when receiving message: #{XS::Util.error_string}"
-  #    end
+  # @example
+  #   received_message = Message.create
+  #   if received_message
+  #     rc = socket.recvmsg(received_message)
+  #     if XS::Util.resultcode_ok?(rc)
+  #       puts "Message contained: #{received_message.copy_out_string}"
+  #     else
+  #       STDERR.puts "Error when receiving message: #{XS::Util.error_string}"
+  #     end
   #
+  # @example Define a custom layout for the data sent between Crossroads peers
+  #   class MyMessage
+  #     class Layout < FFI::Struct
+  #       layout :value1, :uint8,
+  #              :value2, :uint64,
+  #              :value3, :uint32,
+  #              :value4, [:char, 30]
+  #     end
   #
-  # Define a custom layout for the data sent between Crossroads peers.
+  #     def initialize msg_struct = nil
+  #       if msg_struct
+  #         @msg_t = msg_struct
+  #         @data = Layout.new(@msg_t.data)
+  #       else
+  #         @pointer = FFI::MemoryPointer.new :byte, Layout.size, true
+  #         @data = Layout.new @pointer
+  #       end
+  #     end
   #
-  #  class MyMessage
-  #    class Layout < FFI::Struct
-  #      layout :value1, :uint8,
-  #             :value2, :uint64,
-  #             :value3, :uint32,
-  #             :value4, [:char, 30]
-  #    end
+  #     def size() @size = @msg_t.size; end
   #
-  #    def initialize msg_struct = nil
-  #      if msg_struct
-  #        @msg_t = msg_struct
-  #        @data = Layout.new(@msg_t.data)
-  #      else
-  #        @pointer = FFI::MemoryPointer.new :byte, Layout.size, true
-  #        @data = Layout.new @pointer
-  #      end
-  #    end
+  #     def value1
+  #       @data[:value1]
+  #     end
   #
-  #    def size() @size = @msg_t.size; end
+  #     def value4
+  #       @data[:value4].to_ptr.read_string
+  #     end
   #
-  #    def value1
-  #      @data[:value1]
-  #    end
+  #     def value1=(val)
+  #       @data[:value1] = val
+  #     end
   #
-  #    def value4
-  #      @data[:value4].to_ptr.read_string
-  #    end
+  #     def create_sendable_message
+  #       msg = Message.new
+  #       msg.copy_in_bytes @pointer, Layout.size
+  #     end
+  #   end
   #
-  #    def value1=(val)
-  #      @data[:value1] = val
-  #    end
-  #
-  #    def create_sendable_message
-  #      msg = Message.new
-  #      msg.copy_in_bytes @pointer, Layout.size
-  #    end
-  #
-  #
-  #  message = Message.new
-  #  successful_read = socket.recv message
-  #  message = MyMessage.new message if successful_read
-  #  puts "value1 is #{message.value1}"
+  #   message = Message.new
+  #   successful_read = socket.recv message
+  #   message = MyMessage.new message if successful_read
+  #   puts "value1 is #{message.value1}"
   #
   class Message
     include XS::Util
     
-    # Recommended way to create a standard message. A Message object is 
-    # returned upon success, nil when allocation fails.
+    # Recommended way to create a standard message.
     #
+    # @param message (optional)
+    # 
+    # @return [Message] upon success
+    # @return nil when allocation fails
     def self.create message = nil
       new(message) rescue nil
     end
 
+    # Initialize object
+    #
+    # @param message (optional)
     def initialize message = nil
       # allocate our own pointer so that we can tell it to *not* zero out
       # the memory; it's pointless work since the library is going to
@@ -114,6 +120,7 @@ module XS
     #
     # Can only be initialized via #copy_in_string or #copy_in_bytes once.
     #
+    # @param string
     def copy_in_string string
       string_size = string.respond_to?(:bytesize) ? string.bytesize : string.size
       copy_in_bytes string, string_size if string
@@ -124,6 +131,8 @@ module XS
     #
     # Can only be initialized via #copy_in_string or #copy_in_bytes once.
     #
+    # @param bytes
+    # @param length
     def copy_in_bytes bytes, len
       data_buffer = LibC.malloc len
       # writes the exact number of bytes, no null byte to terminate string
@@ -138,22 +147,26 @@ module XS
     # Provides the memory address of the +xs_msg_t+ struct. Used mostly for
     # passing to other methods accessing the underlying library that
     # require a real data address.
-    #
     def address
       @pointer
     end
     alias :pointer :address
 
+    # Copy content of message to another message
+    #
+    # @param source
     def copy source
       LibXS.xs_msg_copy @pointer, source
     end
 
+    # Move content of message to another message
+    #
+    # @param source
     def move source
       LibXS.xs_msg_move @pointer, source
     end
 
     # Provides the size of the data buffer for this +xs_msg_t+ C struct.
-    #
     def size
       LibXS.xs_msg_size @pointer
     end
@@ -163,6 +176,7 @@ module XS
     # when the +message+ object goes out of scope and gets garbage
     # collected.
     #
+    # @return pointer
     def data
       LibXS.xs_msg_data @pointer
     end
@@ -171,6 +185,7 @@ module XS
     #
     # Note: If this is binary data, it won't print very prettily.
     #
+    # @return string
     def copy_out_string
       data.read_string(size)
     end
@@ -181,6 +196,8 @@ module XS
     # Only releases the buffer a single time. Subsequent calls are
     # no ops.
     #
+    # @return 0 if successful
+    # @return -1 if unsuccessful
     def close
       rc = 0
       
@@ -196,6 +213,7 @@ module XS
     # each new instance
     @msg_size = LibXS::Msg.size
     
+    # Store the message size
     def self.msg_size() @msg_size; end
 
   end # class Message
@@ -231,6 +249,11 @@ module XS
     # Makes a copy of +len+ bytes from the ruby string +bytes+. Library
     # handles deallocation of the native memory buffer.
     #
+    # @param bytes
+    # @param length
+    #
+    # @return 0 if successful
+    # @return -1 if unsuccessful
     def copy_in_bytes bytes, len
       rc = super(bytes, len)
       
@@ -243,6 +266,8 @@ module XS
     # Manually release the message struct and its associated data
     # buffer.
     #
+    # @return 0 if successful
+    # @return -1 if unsuccessful
     def close
       rc = super()
       remove_finalizer
@@ -252,10 +277,12 @@ module XS
 
     private
 
+    # Deletes native resources after object has been destroyed
     def define_finalizer
       ObjectSpace.define_finalizer(self, self.class.close(@pointer))
     end
 
+    # Removes all finalizers for object
     def remove_finalizer
       ObjectSpace.undefine_finalizer self
     end
@@ -265,6 +292,8 @@ module XS
     # This is intentional. Since this code runs as a finalizer, there is no
     # way to catch a raised exception anywhere near where the error actually
     # occurred in the code, so we just ignore deallocation failures here.
+    #
+    # @param pointer
     def self.close ptr
       Proc.new do
         # release the data buffer

data/lib/ffi-rxs/poll.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 module XS
 
@@ -28,16 +29,14 @@ module XS
     # this possible condition (via #size) and throttle the call
     # frequency.
     #
-    # Returns 0 when there are no registered sockets that are readable
-    # or writable. 
-    # 
-    # Return 1 (or greater) to indicate the number of readable or writable
-    # sockets. These sockets should be processed using the #readables and
-    # #writables accessors.
+    # @param timeout
     #
-    # Returns -1 when there is an error. Use XS::Util.errno to get the related
+    # @return 0 when there are no readable/writeable registered sockets
+    # @return number to indicate the number of readable or writable sockets
+    # @return -1 when there is an error
+    
+    # When return code -1 use XS::Util.errno to get the related
     # error number.
-    #
     def poll timeout = :blocking
       unless @items.empty?
         timeout = adjust timeout
@@ -56,9 +55,9 @@ module XS
     # The non-blocking version of #poll. See the #poll description for
     # potential exceptions.
     #
-    # May return -1 when an error is encounted. Check XS::Util.errno
-    # to determine the underlying cause.
+    # @return -1 when an error is encountered.
     #
+    # When return code -1 check XS::Util.errno to determine the underlying cause.
     def poll_nonblock
       poll 0
     end
@@ -68,6 +67,12 @@ module XS
     # will only get registered at most once. Calling multiple times with
     # different values for +events+ will OR the event information together.
     #
+    # @param socket
+    # @param events
+    #   One of @XS::POLLIN@ and @XS::POLLOUT@
+    #
+    # @return true if successful
+    # @return false if not
     def register sock, events = XS::POLLIN | XS::POLLOUT, fd = 0
       return false if (sock.nil? && fd.zero?) || events.zero?
 
@@ -76,7 +81,6 @@ module XS
       unless item
         @sockets << sock
         item = LibXS::PollItem.new
-
         if sock.kind_of?(XS::Socket) || sock.kind_of?(Socket)
           item[:socket] = sock.socket
           item[:fd] = 0
@@ -95,6 +99,12 @@ module XS
     # Deregister the +sock+ for +events+. When there are no events left,
     # this also deletes the socket from the poll items.
     #
+    # @param socket
+    # @param events
+    #   One of @XS::POLLIN@ and @XS::POLLOUT@
+    #
+    # @return true if successful
+    # @return false if not
     def deregister sock, events, fd = 0
       return unless sock || !fd.zero?
 
@@ -113,24 +123,40 @@ module XS
 
     # A helper method to register a +sock+ as readable events only.
     #
+    # @param socket
+    #
+    # @return true if successful
+    # @return false if not
     def register_readable sock
       register sock, XS::POLLIN, 0
     end
 
     # A helper method to register a +sock+ for writable events only.
     #
+    # @param socket
+    #
+    # @return true if successful
+    # @return false if not
     def register_writable sock
       register sock, XS::POLLOUT, 0
     end
 
     # A helper method to deregister a +sock+ for readable events.
     #
+    # @param socket
+    #
+    # @return true if successful
+    # @return false if not
     def deregister_readable sock
       deregister sock, XS::POLLIN, 0
     end
 
     # A helper method to deregister a +sock+ for writable events.
     #
+    # @param socket
+    #
+    # @return true if successful
+    # @return false if not
     def deregister_writable sock
       deregister sock, XS::POLLOUT, 0
     end
@@ -142,6 +168,10 @@ module XS
     # Can also be called directly to remove the socket from the polling
     # array.
     #
+    # @param socket
+    #
+    # @return true if successful
+    # @return false if not
     def delete sock
       unless (size = @sockets.size).zero?
         @sockets.delete_if { |socket| socket.socket.address == sock.socket.address }
@@ -158,23 +188,32 @@ module XS
       end
     end
 
+    # Convenience method to return size of items array
     def size(); @items.size; end
 
+    # Convenience method to inspect items array
     def inspect
       @items.inspect
     end
 
+    # Convenience method to inspect poller
     def to_s(); inspect; end
 
 
     private
 
+    # Create hash of items
+    #
+    # @param empty hash
+    #
+    # @return hash
     def items_hash hash
       @items.each do |poll_item|
         hash[@raw_to_socket[poll_item.socket.address]] = poll_item
       end
     end
 
+    # Update readables and writeables
     def update_selectables
       @readables.clear
       @writables.clear
@@ -199,7 +238,10 @@ module XS
     # Users will pass in values measured as
     # milliseconds, so we need to convert that value to
     # microseconds for the library.
-    
+    #
+    # @param timeout
+    #
+    # @return number   
     def adjust timeout
       if :blocking == timeout || -1 == timeout
         -1

data/lib/ffi-rxs/poll_items.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 
 module XS
   class PollItems
@@ -22,7 +23,7 @@ module XS
       unless @items.empty? || index.nil?
         clean
 
-        # pointer arithmetic in ruby! whee!
+        # pointer arithmetic in ruby
         pointer = @store + (@element_size * index)
 
         # cast the memory to a PollItem