polyphony 0.99.4 → 0.99.6

data/ext/polyphony/polyphony.c

@@ -27,31 +27,23 @@ ID ID_R;
 ID ID_W;
 ID ID_RW;
 
-/* call-seq:
- *   snooze
- *   Polyphony.snooze
- *
- * Switches to the next fiber in the current thread's runqueue after adding the
+/* Switches to the next fiber in the current thread's runqueue after adding the
  * current fiber to the runqueue. This lets other fibers run, letting the
  * current fiber eventually continue its work. This call is useful when
  * performing long-running calculations in order to keep the program responsive.
- * 
- * @return [void]
+ *
+ * @return [any] resume value
  */
 
 VALUE Polyphony_snooze(VALUE self) {
   return Backend_snooze(BACKEND());
 }
 
-/* call-seq:
- *   suspend
- *   Polyphony.suspend
- *
- * Switches to the next fiber in the current thread's runqueue without
+/* Switches to the next fiber in the current thread's runqueue without
  * rescheduling the current fiber. This is useful if the current fiber does not
  * need to continue or will be scheduled by other means eventually.
- * 
- * @return [void]
+ *
+ * @return [any] resume value
  */
 
 static VALUE Polyphony_suspend(VALUE self) {
@@ -62,15 +54,12 @@ static VALUE Polyphony_suspend(VALUE self) {
   return ret;
 }
 
-/* call-seq:
- *   Polyphony.backend_accept(server_socket, socket_class) -> socket
- *
- * Accepts an incoming connection on the given server socket, returning an
+/* Accepts an incoming connection on the given server socket, returning an
  * instance of the given socket class.
- * 
+ *
  * @param server_socket [Socket] socket to accept on
  * @param socket_class [Class] class of the socket to instantiate for the accepted connection
- * 
+ *
  * @return [Socket] accepted connection
  */
 
@@ -78,16 +67,13 @@ VALUE Polyphony_backend_accept(VALUE self, VALUE server_socket, VALUE socket_cla
   return Backend_accept(BACKEND(), server_socket, socket_class);
 }
 
-/* call-seq:
- *   Polyphony.backend_accept_loop(server_socket, socket_class) { |socket| ... }
- *
- * Runs an infinite loop accepting connections on the given server socket,
+/* Runs an infinite loop accepting connections on the given server socket,
  * returning an instance of the given socket class.
- * 
+ *
  * @param server_socket [Socket] socket to accept on
  * @param socket_class [Class] class of the socket to instantiate for the accepted connection
- * @yield [Socket] accepted connection passed to the given block
- * @return [void]
+ * @yield [Socket] accepted connection
+ * @return [nil]
  */
 
 VALUE Polyphony_backend_accept_loop(VALUE self, VALUE server_socket, VALUE socket_class) {
@@ -95,14 +81,11 @@ VALUE Polyphony_backend_accept_loop(VALUE self, VALUE server_socket, VALUE socke
 }
 
 #ifdef HAVE_IO_URING_PREP_MULTISHOT_ACCEPT
-/* call-seq:
- *   Polyphony.backend_multishot_accept(server_socket) { ... }
- *
- * Starts a multishot accept operation on the given server socket. This API is
+/* Starts a multishot accept operation on the given server socket. This API is
  * available only for the io_uring backend.
- * 
+ *
  * @param server_socket [Socket] socket to accept on
- * @return [void]
+ * @return [any] block return value
  */
 
 VALUE Polyphony_backend_multishot_accept(VALUE self, VALUE server_socket) {
@@ -111,15 +94,12 @@ VALUE Polyphony_backend_multishot_accept(VALUE self, VALUE server_socket) {
 #endif
 
 
-/* call-seq:
- *   Polyphony.backend_connect(socket, addr, port) -> socket
+/* Connects the given socket to the given address and port.
  *
- * Connects the given socket to the given address and port.
- * 
  * @param io [Socket] socket to connect
  * @param addr [String] address to connect to
  * @param port [Integer] port to connect to
- * 
+ *
  * @return [Socket] accepted connection
  */
 
@@ -127,36 +107,29 @@ VALUE Polyphony_backend_connect(VALUE self, VALUE io, VALUE addr, VALUE port) {
   return Backend_connect(BACKEND(), io, addr, port);
 }
 
-/* call-seq:
- *   Polyphony.backend_feed_loop(io, receiver, method)
+/* Runs a feed loop, reading data from the given io, feeding it to the receiver
+ * with the given method. The loop terminates when EOF is encountered. If a
+ * block is given, it is used as the block for the method call to the receiver.
  *
- * Runs a feed loop, reading data from the given io, feeding it to the receiver
- * with the given method, and passing the receiver's output to the given block.
- * The loop terminates when EOF is encountered.
- * 
  * @param io [IO] io to read from
  * @param receiver [any] an object receiving the data
  * @param method [Symbol] method used to feed the data to the receiver
- * @yield [any] data passed to the given block
- * 
- * @return [void]
+ *
+ * @return [IO] io
  */
 
 VALUE Polyphony_backend_feed_loop(VALUE self, VALUE io, VALUE receiver, VALUE method) {
   return Backend_feed_loop(BACKEND(), io, receiver, method);
 }
 
-/* call-seq:
- *   Polyphony.backend_read(io, buffer, length, to_eof, pos) -> buffer
+/* Reads from the given io.
  *
- * Reads from the given io.
- * 
  * @param io [IO] io to read from
  * @param buffer [String, nil] buffer to read into
  * @param length [Integer] maximum bytes to read
  * @param to_eof [boolean] whether to read to EOF
  * @param pos [Integer] Position in the buffer to read into
- * 
+ *
  * @return [String] buffer
  */
 
@@ -164,32 +137,26 @@ VALUE Polyphony_backend_read(VALUE self, VALUE io, VALUE buffer, VALUE length, V
   return Backend_read(BACKEND(), io, buffer, length, to_eof, pos);
 }
 
-/* call-seq:
- *   Polyphony.backend_read_loop(io, max_len)
- *
- * Performs an infinite loop reading data from the given io. The loop terminates
+/* Performs an infinite loop reading data from the given io. The loop terminates
  * when EOF is encountered.
- * 
+ *
  * @param io [IO] io to read from
  * @param maxlen [Integer] maximum bytes to read
- * 
- * @return [void]
+ *
+ * @return [IO] io
  */
 
 VALUE Polyphony_backend_read_loop(VALUE self, VALUE io, VALUE maxlen) {
   return Backend_read_loop(BACKEND(), io, maxlen);
 }
 
-/* call-seq:
- *   Polyphony.backend_recv(io, buffer, length, pos) -> buffer
+/* Receives data on the given io.
  *
- * Receives data on the given io.
- * 
  * @param io [Socket] io to receive on
  * @param buffer [String, nil] buffer to read into
  * @param length [Integer] maximum bytes to read
  * @param pos [Integer] Position in the buffer to read into
- * 
+ *
  * @return [String] buffer
  */
 
@@ -197,11 +164,8 @@ VALUE Polyphony_backend_recv(VALUE self, VALUE io, VALUE buffer, VALUE length, V
   return Backend_recv(BACKEND(), io, buffer, length, pos);
 }
 
-/* call-seq:
- *   Polyphony.backend_recvmsg(socket, buffer, maxlen, pos, flags, maxcontrollen, opts) -> buffer
+/* Receives a message on the given socket.
  *
- * Receives a message on the given socket.
- * 
  * @param socket [UDPSocket] io to receive on
  * @param buffer [String, nil] buffer to read into
  * @param maxlen [Integer] maximum bytes to read
@@ -209,7 +173,6 @@ VALUE Polyphony_backend_recv(VALUE self, VALUE io, VALUE buffer, VALUE length, V
  * @param flags [Integer] Flags
  * @param maxcontrollen [Integer] Maximum control bytes
  * @param opts [Hash] Options
- * 
  * @return [String] buffer
  */
 
@@ -217,50 +180,41 @@ VALUE Polyphony_backend_recvmsg(VALUE self, VALUE socket, VALUE buffer, VALUE ma
   return Backend_recvmsg(BACKEND(), socket, buffer, maxlen, pos, flags, maxcontrollen, opts);
 }
 
-/* call-seq:
- *   Polyphony.backend_recv_loop(socket, max_len)
+/* Performs an infinite loop receiving data on the given socket. The loop
+ * terminates when the socket is closed.
  *
- * Performs an infinite loop receiving data on the given socket. The loop terminates
- * when the socket is closed.
- * 
  * @param socket [Socket] socket to receive on
  * @param maxlen [Integer] maximum bytes to read
- * 
- * @return [void]
+ * @yield [data] received data
+ * @return [Socket] socket
  */
 
 VALUE Polyphony_backend_recv_loop(VALUE self, VALUE socket, VALUE maxlen) {
   return Backend_recv_loop(BACKEND(), socket, maxlen);
 }
 
-/* call-seq:
- *   Polyphony.backend_recv_feed_loop(socket, receiver, method)
+/* Runs a feed loop, receiving data on the given socket, feeding it to the
+ * receiver with the given method. The loop terminates when EOF is encountered.
+ * If a block is given, it is used as the block for the method call to the
+ * receiver.
  *
- * Runs a feed loop, receiving data on the given socket, feeding it to the receiver
- * with the given method, and passing the receiver's output to the given block.
- * The loop terminates when EOF is encountered.
- * 
  * @param socket [Socket] socket to receive on
  * @param receiver [any] an object receiving the data
  * @param method [Symbol] method used to feed the data to the receiver
- * @yield [any] data passed to the given block
- * 
- * @return [void]
+ *
+ * @return [Socket] socket
  */
 
 VALUE Polyphony_backend_recv_feed_loop(VALUE self, VALUE socket, VALUE receiver, VALUE method) {
   return Backend_recv_feed_loop(BACKEND(), socket, receiver, method);
 }
 
-/* call-seq:
- *   Polyphony.backend_send(socket, msg, flags) -> bytes_sent
+/* Sends data on the given socket, returning the number of bytes sent.
  *
- * Sends data on the given socket, returning the number of bytes sent.
- * 
  * @param socket [Socket] socket to read from
  * @param msg [String] data to be sent
  * @param flags [Integer] Flags
- * 
+ *
  * @return [Integer] number of bytes sent
  */
 
@@ -268,11 +222,8 @@ VALUE Polyphony_backend_send(VALUE self, VALUE socket, VALUE msg, VALUE flags) {
   return Backend_send(BACKEND(), socket, msg, flags);
 }
 
-/* call-seq:
- *   Polyphony.backend_sendmsg(socket, msg, flags, dest_sockaddr, controls) -> bytes_sent
+/* Sends data on the given socket, returning the number of bytes sent.
  *
- * Sends data on the given socket, returning the number of bytes sent.
- * 
  * @param socket [Socket] socket to read from
  * @param msg [String] data to be sent
  * @param flags [Integer] Flags
@@ -285,11 +236,9 @@ VALUE Polyphony_backend_sendmsg(VALUE self, VALUE socket, VALUE msg, VALUE flags
   return Backend_sendmsg(BACKEND(), socket, msg, flags, dest_sockaddr, controls);
 }
 
-/* call-seq:
- *   Polyphony.backend_sendv(socket, ary, flags) -> bytes_sent
+/* Sends multiple strings on the given socket, returning the number of bytes
+ * sent.
  *
- * Sends multiple strings on the given socket, returning the number of bytes sent.
- * 
  * @param socket [Socket] socket to read from
  * @param ary [Array<String>] data to be sent
  * @param flags [Integer] Flags
@@ -300,25 +249,19 @@ VALUE Polyphony_backend_sendv(VALUE self, VALUE socket, VALUE ary, VALUE flags)
   return Backend_sendv(BACKEND(), socket, ary, flags);
 }
 
-/* call-seq:
- *   Polyphony.backend_sleep(duration)
+/* Sleeps for the given duration, yielding execution to other fibers.
  *
- * Sleeps for the given duration, yielding execution to other fibers.
- * 
  * @param duration [Number] duration in seconds
- * @return [void]
+ * @return [nil]
  */
 
 VALUE Polyphony_backend_sleep(VALUE self, VALUE duration) {
   return Backend_sleep(BACKEND(), duration);
 }
 
-/* call-seq:
- *   Polyphony.backend_splice(src, dest, maxlen) -> bytes_spliced
- *
- * Splices data from the given source to the given destination, returning the
+/* Splices data from the given source to the given destination, returning the
  * number of bytes spliced.
- * 
+ *
  * @param src [IO] source
  * @param dest [IO] destination
  * @param maxlen [Integer] Maximum bytes to splice
@@ -345,69 +288,57 @@ VALUE Polyphony_backend_tee(VALUE self, VALUE src, VALUE dest, VALUE chunksize)
 }
 #endif
 
-/* call-seq:
- *   Polyphony.backend_timeout(duration) { ... }
- *   Polyphony.backend_timeout(duration, exception_class) { ... }
- *
- * Runs the given block, raising an exception if the block has not finished
+/* Runs the given block, raising an exception if the block has not finished
  * running before a timeout has elapsed, using the given duration. If an
  * exception class is not given, a TimeoutError is raised.
- * 
+ *
+ * @overload backend_timeout(duration)
+ *   @param duration [Number] timeout duration in seconds
+ *   @return [any] return value of block
+ * @overload backend_timeout(duration, exception_class)
+ *   @param duration [Number] timeout duration in seconds
+ *   @param exception_class [Class] exception class to raise in case of timeout
+ *   @return [any] return value of block
  */
 
 VALUE Polyphony_backend_timeout(int argc,VALUE *argv, VALUE self) {
   return Backend_timeout(argc, argv, BACKEND());
 }
 
-/* call-seq:
- *   Polyphony.backend_timer_loop(interval) { ... }
+/* Runs an infinite loop that calls the given block at the specified time interval.
  *
- * Runs an infinite loop that calls the given block at the specified time interval.
- * 
  * @param interval [Number] interval in seconds
- * @yield [] code to run
- * @return [void]
  */
 
 VALUE Polyphony_backend_timer_loop(VALUE self, VALUE interval) {
   return Backend_timer_loop(BACKEND(), interval);
 }
 
-/* call-seq:
- *   Polyphony.backend_wait_event(raise)
- *
- * For for the current fiber to be rescheduled, resuming the fiber with its
+/* For for the current fiber to be rescheduled, resuming the fiber with its
  * resumed value. If raise is true and the resumed value is an exception, an
  * exception will be raised.
- * 
+ *
  * @param raise [boolean]
- * @return [any] resumed value
  */
 
 VALUE Polyphony_backend_wait_event(VALUE self, VALUE raise) {
   return Backend_wait_event(BACKEND(), raise);
 }
 
-/* call-seq:
- *   Polyphony.backend_wait_io(io, read_or_write)
- *
- * Waits for the given IO to be readable or writeable, according to the
+/* Waits for the given IO to be readable or writeable, according to the
  * read_or_write parameter.
- * 
+ *
  * @param io [IO]
  * @param write [boolean] false for read, true for write
- * @return [void]
+ * @return [nil]
  */
 
 VALUE Polyphony_backend_wait_io(VALUE self, VALUE io, VALUE write) {
   return Backend_wait_io(BACKEND(), io, write);
 }
 
-/* call-seq:
- *   Polyphony.backend_wait_pid(pid) -> exit code
+/* Waits for the given process to terminate, returning its exit code.
  *
- * Waits for the given process to terminate, returning its exit code.
- * 
  * @param pid [Integer] pid
  * @return [Integer] exit code
  */
@@ -416,10 +347,7 @@ VALUE Polyphony_backend_waitpid(VALUE self, VALUE pid) {
   return Backend_waitpid(BACKEND(), pid);
 }
 
-/* call-seq:
- *   Polyphony.backend_write(io, data, ...) -> bytes_written
- *
- * Writes one or more strings to the given io, returning the total number of
+/* Writes one or more strings to the given io, returning the total number of
  * bytes written.
  */
 
@@ -450,7 +378,7 @@ VALUE Polyphony_raw_buffer_get(int argc, VALUE *argv, VALUE self) {
 
   struct buffer_spec *buffer_spec = FIX2PTR(buf);
   int length = (len == Qnil) ? buffer_spec->len : FIX2INT(len);
-  
+
   if (length > buffer_spec->len) length = buffer_spec->len;
   return rb_utf8_str_new((char *)buffer_spec->ptr, length);
 }
@@ -462,7 +390,7 @@ VALUE Polyphony_raw_buffer_set(VALUE self, VALUE buffer, VALUE str) {
   int len = RSTRING_LEN(str);
   if (len > buffer_spec->len)
     rb_raise(rb_eRuntimeError, "Given string does not fit in given buffer");
-  
+
   memcpy(buffer_spec->ptr, RSTRING_PTR(str), len);
   buffer_spec->len = len;
   return self;
@@ -504,7 +432,7 @@ void Init_Polyphony(void) {
   rb_define_singleton_method(mPolyphony, "backend_sendv", Polyphony_backend_sendv, 3);
   rb_define_singleton_method(mPolyphony, "backend_sleep", Polyphony_backend_sleep, 1);
   rb_define_singleton_method(mPolyphony, "backend_splice", Polyphony_backend_splice, 3);
- 
+
   #ifdef POLYPHONY_BACKEND_LIBURING
   rb_define_singleton_method(mPolyphony, "backend_double_splice", Polyphony_backend_double_splice, 2);
   #endif
@@ -512,7 +440,7 @@ void Init_Polyphony(void) {
   #ifdef POLYPHONY_LINUX
   rb_define_singleton_method(mPolyphony, "backend_tee", Polyphony_backend_tee, 3);
   #endif
-  
+
   rb_define_singleton_method(mPolyphony, "backend_timeout", Polyphony_backend_timeout, -1);
   rb_define_singleton_method(mPolyphony, "backend_timer_loop", Polyphony_backend_timer_loop, 1);
   rb_define_singleton_method(mPolyphony, "backend_wait_event", Polyphony_backend_wait_event, 1);

data/ext/polyphony/queue.c

@@ -61,16 +61,14 @@ static VALUE Queue_allocate(VALUE klass) {
 #define GetQueue(obj, queue) \
   TypedData_Get_Struct((obj), Queue_t, &Queue_type, (queue))
 
-/* call-seq:
- *   Queue.new -> queue
- *   Queue.new(capacity) -> queue
- *
- * Initializes a queue instance. If the capacity is given, the queue becomes
+/* Initializes a queue instance. If the capacity is given, the queue becomes
  * capped, i.e. it cannot contain more elements than its capacity. When trying
  * to add items to a capped queue that is full, the current fiber will block
  * until at least one item is removed from the queue.
- * 
- * @return [void]
+ *
+ * @overload new()
+ * @overload new(capacity)
+ *   @param capacity [Integer] maximum items in queue
  */
 
 static VALUE Queue_initialize(int argc, VALUE *argv, VALUE self) {
@@ -131,7 +129,7 @@ static inline void capped_queue_block_push(Queue_t *queue) {
  *
  * Adds the given value to the queue's end. If the queue is capped and full, the
  * call will block until a value is removed from the queue.
- * 
+ *
  * @param value [any] value to be added to the queue
  * @return [Queue] self
  */
@@ -151,12 +149,9 @@ VALUE Queue_push(VALUE self, VALUE value) {
   return self;
 }
 
-/* call-seq:
- *   queue.unshift(value) -> queue
- *
- * Adds the given value to the queue's beginning. If the queue is capped and
+/* Adds the given value to the queue's beginning. If the queue is capped and
  * full, the call will block until a value is removed from the queue.
- * 
+ *
  * @param value [any] value to be added to the queue
  * @return [Queue] self
  */
@@ -230,6 +225,7 @@ VALUE Queue_shift_block(Queue_t *queue) {
  * the queue is empty, a ThreadError exception is raised. In blocking mode, if
  * the queue is empty, the call will block until an item is added to the queue.
  *
+ * @param nonblock [boolean] non-blocking mode
  * @return [any] first value in queue
  */
 
@@ -243,10 +239,7 @@ VALUE Queue_shift(int argc,VALUE *argv, VALUE self) {
     Queue_shift_block(queue);
 }
 
-/* call-seq:
- *   queue.delete(value) -> queue
- *
- * Removes the given value from the queue.
+/* Removes the given value from the queue.
  *
  * @return [Queue] self
  */
@@ -263,10 +256,7 @@ VALUE Queue_delete(VALUE self, VALUE value) {
   return self;
 }
 
-/* call-seq:
- *   queue.cap(capacity) -> queue
- *
- * Sets the capacity for the queue to the given value. If 0 or nil is given, the
+/* Sets the capacity for the queue to the given value. If 0 or nil is given, the
  * queue becomes uncapped.
  *
  * @param cap [Integer, nil] new capacity
@@ -287,10 +277,7 @@ VALUE Queue_cap(VALUE self, VALUE cap) {
   return self;
 }
 
-/* call-seq:
- *   queue.capped? -> bool
- *
- * Returns true if the queue is capped.
+/* Returns true if the queue is capped.
  *
  * @return [boolean] is the queue capped
  */
@@ -302,10 +289,7 @@ VALUE Queue_capped_p(VALUE self) {
   return queue->capacity ? INT2FIX(queue->capacity) : Qnil;
 }
 
-/* call-seq:
- *   queue.clear -> queue
- *
- * Removes all values from the queue.
+/* Removes all values from the queue.
  *
  * @return [Queue] self
  */
@@ -327,13 +311,10 @@ long Queue_len(VALUE self) {
   return queue->values.count;
 }
 
-/* call-seq:
- *   queue.shift_each { |value| do_something(value) } -> queue
- *
- * Iterates over all values in the queue, removing each item and passing it to
+/* Iterates over all values in the queue, removing each item and passing it to
  * the given block.
  *
- * @yield [any] value passed to the given block
+ * @yield [any] removed item
  * @return [Queue] self
  */
 
@@ -346,10 +327,7 @@ VALUE Queue_shift_each(VALUE self) {
   return self;
 }
 
-/* call-seq:
- *   queue.shift_all -> array
- *
- * Returns all values currently in the queue, clearing the queue.
+/* Returns all values currently in the queue, clearing the queue.
  *
  * @return [Array] all values
  */
@@ -365,10 +343,7 @@ VALUE Queue_shift_all(VALUE self) {
   return result;
 }
 
-/* call-seq:
- *   queue.flush_waiters -> queue
- *
- * Flushes all fibers currently blocked waiting to remove items from the queue,
+/* Flushes all fibers currently blocked waiting to remove items from the queue,
  * resuming them with the given value.
  *
  * @param value [any] value to resome all waiting fibers with
@@ -389,10 +364,7 @@ VALUE Queue_flush_waiters(VALUE self, VALUE value) {
   return self;
 }
 
-/* call-seq:
- *   queue.empty? -> bool
- *
- * Returns true if the queue is empty.
+/* Returns true if the queue is empty.
  *
  * @return [boolean]
  */
@@ -404,10 +376,7 @@ VALUE Queue_empty_p(VALUE self) {
   return (!queue->values.count) ? Qtrue : Qfalse;
 }
 
-/* call-seq:
- *   queue.pending? -> bool
- *
- * Returns true if any fibers are currently waiting to remove items from the
+/* Returns true if any fibers are currently waiting to remove items from the
  * queue.
  *
  * @return [boolean]
@@ -420,10 +389,7 @@ VALUE Queue_pending_p(VALUE self) {
   return (queue->shift_queue.count) ? Qtrue : Qfalse;
 }
 
-/* call-seq:
- *   queue.num_waiting -> integer
- *
- * Returns the number of fibers currently waiting to remove items from the
+/* Returns the number of fibers currently waiting to remove items from the
  * queue.
  *
  * @return [Integer]
@@ -438,7 +404,7 @@ VALUE Queue_num_waiting(VALUE self) {
 
 /* call-seq:
  *   queue.size -> integer
- *   queue.length -> integer 
+ *   queue.length -> integer
  *
  * Returns the number of values currently in the queue.
  *
@@ -452,10 +418,7 @@ VALUE Queue_size_m(VALUE self) {
   return INT2FIX(queue->values.count);
 }
 
-/* call-seq:
- *   queue.closed? -> bool
- *
- * Returns true if the queue has been closed.
+/* Returns true if the queue has been closed.
  *
  * @return [boolean]
  */
@@ -467,10 +430,7 @@ VALUE Queue_closed_p(VALUE self) {
   return (queue->closed) ? Qtrue : Qfalse;
 }
 
-/* call-seq:
- *   queue.close -> queue
- *
- * Marks the queue as closed. Any fibers currently waiting on the queue are
+/* Marks the queue as closed. Any fibers currently waiting on the queue are
  * resumed with a `nil` value. After the queue is closed, trying to remove items
  * from the queue will cause a `ClosedQueueError` to be raised.
  *