polyphony 0.99.5 → 0.99.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d73317fd0bed90e2966bcf71e0f89d13318c21a4d235127162c3ed1d4f7ee2ea
-  data.tar.gz: bad470bf595168aec1e8cac95b6b707d82a1f10a4e9c2cdc33d35194d0bb4a53
+  metadata.gz: 4a2733c956cab37dac192c107c4c2def808595601cca177dfbfcbd23b3b291e7
+  data.tar.gz: 417aacff2dac6ec2f4cfe85c8afc0bab21a5d20ac8748a3a5ceca42ec7950b8c
 SHA512:
-  metadata.gz: 7e64aafec751da5932e1782acd28a29c6661ae76a223b9edaa6445b1d4c2728b2a185a98b86d4d87ace5ca35522030d68b902b0679c95dfd82783e3f12d8d9a8
-  data.tar.gz: bdac913bc057e31cb51f47b6624e62e59f071db050480a64f73a5273a187243944487df86383d4970e1082a2032f624205791ab7b43f98f64385bccf6918ac8a
+  metadata.gz: 7c5d41ad9927a1b3770b76b702bc3f7695d4fb0c87601df3a5fd9d25cdc3e121881ec4e9dbbe618234864c73b8ac67cf1f9156a5bc031a7186d9633a03d70e00
+  data.tar.gz: ad66aab4d2fb6b60f702791036fa8883b6e262eadee7170dc285d68903b2447d17160aec9e382c336ace24e3e0379d25683ba736084df6c61c36858b465513e4

data/.rubocop.yml

@@ -99,6 +99,7 @@ Metrics/ClassLength:
     - lib/polyphony/http/server/http1.rb
     - lib/polyphony/extensions/io.rb
     - lib/polyphony/extensions/fiber.rb
+    - lib/polyphony/extensions/object.rb
     - test/**/*.rb
     - examples/**/*.rb
 

data/.yardopts

@@ -3,7 +3,6 @@
 --verbose
 --protected
 --no-private
---asset assets/:assets
 --exclude debugger.rb
 --exclude redis.rb
 --exclude readline.rb
@@ -14,7 +13,6 @@
 --exclude sequel.rb
 --exclude event.c
 --exclude backend.+\.c
-# --load ./docs/link_rewriter.rb
 -r docs/readme.md
 ./lib
 ./ext/polyphony

data/README.md

@@ -1,4 +1,4 @@
-<img src="https://github.com/digital-fabric/polyphony/raw/master/assets/polyphony-logo.png">
+<img src="https://github.com/digital-fabric/polyphony/raw/master/docs/assets/polyphony-logo.png">
 
 # Polyphony: Fine-Grained Concurrency for Ruby
 

data/docs/readme.md

@@ -1,6 +1,6 @@
 # @title README
 
-<img src="https://github.com/digital-fabric/polyphony/raw/master/assets/polyphony-logo.png">
+<img src="https://github.com/digital-fabric/polyphony/raw/master/docs/assets/polyphony-logo.png">
 
 # Polyphony: Fine-Grained Concurrency for Ruby
 

data/docs/tutorial.md

@@ -94,7 +94,7 @@ The above program does nothing exceptional, it just sleeps for 1 second and
 prints a bunch of messages. But it is enough to demonstrate how concurrency
 works in Polyphony. Here's a flow chart of the transfer of control:
 
-<img src="../assets/sleeping-fiber.svg">
+<img src="https://github.com/digital-fabric/polyphony/raw/master/docs/assets/sleeping-fiber.png">
 
 Here's the actual sequence of execution (in pseudo-code)
 
@@ -189,7 +189,7 @@ innocent call to `#spin`.
 
 Here's a flow chart showing the transfer of control between the different fibers:
 
-<img src="../assets/echo-fibers.svg">
+<img src="https://github.com/digital-fabric/polyphony/raw/master/docs/assets/echo-fibers.png">
 
 Let's consider the advantage of the Polyphony concurrency model:
 

data/ext/polyphony/fiber.c

@@ -116,7 +116,7 @@ static VALUE Fiber_state(VALUE self) {
  * mailbox.
  *
  * @param msg [any]
- * @return [void]
+ * @return [Fiber] self
  */
 
 VALUE Fiber_send(VALUE self, VALUE msg) {

data/ext/polyphony/pipe.c

@@ -37,8 +37,6 @@ static VALUE Pipe_allocate(VALUE klass) {
   TypedData_Get_Struct((obj), Pipe_t, &Pipe_type, (pipe))
 
 /* Creates a new pipe.
- *
- * @return [void]
  */
 
 static VALUE Pipe_initialize(VALUE self) {

data/ext/polyphony/polyphony.c

@@ -32,7 +32,7 @@ ID ID_RW;
  * 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) {
@@ -43,7 +43,7 @@ VALUE Polyphony_snooze(VALUE self) {
  * 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) {
@@ -73,7 +73,7 @@ VALUE Polyphony_backend_accept(VALUE self, VALUE server_socket, VALUE socket_cla
  * @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
- * @return [void]
+ * @return [nil]
  */
 
 VALUE Polyphony_backend_accept_loop(VALUE self, VALUE server_socket, VALUE socket_class) {
@@ -85,7 +85,7 @@ VALUE Polyphony_backend_accept_loop(VALUE self, VALUE server_socket, VALUE socke
  * 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) {
@@ -143,7 +143,7 @@ VALUE Polyphony_backend_read(VALUE self, VALUE io, VALUE buffer, VALUE length, V
  * @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) {
@@ -186,7 +186,7 @@ VALUE Polyphony_backend_recvmsg(VALUE self, VALUE socket, VALUE buffer, VALUE ma
  * @param socket [Socket] socket to receive on
  * @param maxlen [Integer] maximum bytes to read
  * @yield [data] received data
- * @return [void]
+ * @return [Socket] socket
  */
 
 VALUE Polyphony_backend_recv_loop(VALUE self, VALUE socket, VALUE maxlen) {
@@ -202,7 +202,7 @@ VALUE Polyphony_backend_recv_loop(VALUE self, VALUE socket, VALUE maxlen) {
  * @param receiver [any] an object receiving the data
  * @param method [Symbol] method used to feed the data to the receiver
  *
- * @return [void]
+ * @return [Socket] socket
  */
 
 VALUE Polyphony_backend_recv_feed_loop(VALUE self, VALUE socket, VALUE receiver, VALUE method) {
@@ -252,7 +252,7 @@ VALUE Polyphony_backend_sendv(VALUE self, VALUE socket, VALUE ary, VALUE flags)
 /* 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) {
@@ -308,7 +308,6 @@ VALUE Polyphony_backend_timeout(int argc,VALUE *argv, VALUE self) {
 /* Runs an infinite loop that calls the given block at the specified time interval.
  *
  * @param interval [Number] interval in seconds
- * @return [void]
  */
 
 VALUE Polyphony_backend_timer_loop(VALUE self, VALUE interval) {
@@ -320,7 +319,6 @@ VALUE Polyphony_backend_timer_loop(VALUE self, VALUE interval) {
  * exception will be raised.
  *
  * @param raise [boolean]
- * @return [any] resumed value
  */
 
 VALUE Polyphony_backend_wait_event(VALUE self, VALUE raise) {
@@ -332,7 +330,7 @@ VALUE Polyphony_backend_wait_event(VALUE self, VALUE raise) {
  *
  * @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) {

data/ext/polyphony/queue.c

@@ -67,10 +67,8 @@ static VALUE Queue_allocate(VALUE klass) {
  * until at least one item is removed from the queue.
  *
  * @overload new()
- *   @return [void]
  * @overload new(capacity)
  *   @param capacity [Integer] maximum items in queue
- *   @return [void]
  */
 
 static VALUE Queue_initialize(int argc, VALUE *argv, VALUE self) {

data/ext/polyphony/thread.c

@@ -44,7 +44,7 @@ inline void Thread_schedule_fiber_with_priority(VALUE self, VALUE fiber, VALUE v
 
 /* Switches to the next fiber in the thread's runqueue.
  *
- * @return [void]
+ * @return [any] resume value
  */
 
 VALUE Thread_switch_fiber(VALUE self) {

data/lib/polyphony/adapters/process.rb

@@ -13,7 +13,7 @@ module Polyphony
       # process is killed.
       #
       # @param cmd [String, nil] command to spawn
-      # @return [void]
+      # @return [true]
       def watch(cmd = nil, &block)
         terminated = nil
         pid = cmd ? Kernel.spawn(cmd) : Polyphony.fork(&block)
@@ -27,7 +27,6 @@ module Polyphony
       # seconds.
       #
       # @param pid [Integer] pid
-      # @return [void]
       def kill_process(pid)
         cancel_after(5) do
           kill_and_await('TERM', pid)
@@ -42,7 +41,6 @@ module Polyphony
       #
       # @param sig [String, Symbol, Integer] signal to use
       # @param pid [Integer] pid
-      # @return [void]
       def kill_and_await(sig, pid)
         ::Process.kill(sig, pid)
         Polyphony.backend_waitpid(pid)

data/lib/polyphony/core/debug.rb

@@ -1,8 +1,6 @@
 # Kernel extensions
 module ::Kernel
   # Prints a trace message to `STDOUT`, bypassing the Polyphony backend.
-  #
-  # @return [void]
   def trace(*args)
     STDOUT.orig_write(format_trace(args))
   end
@@ -33,7 +31,6 @@ module Polyphony
       #
       # @param io [IO, nil] IO instance
       # @yield [Hash] event information
-      # @return [void]
       def start_event_firehose(io = nil, &block)
         Thread.backend.trace_proc = firehose_proc(io, block)
       end

data/lib/polyphony/core/exceptions.rb

@@ -16,7 +16,6 @@ module Polyphony
     # Initializes the exception, setting the caller and the value.
     #
     # @param value [any] Exception value
-    # @return [void]
     def initialize(value = nil)
       @caller_backtrace = caller
       @value = value
@@ -44,14 +43,11 @@ module Polyphony
     # Initializes an Interjection with the given proc.
     #
     # @param proc [Proc] interjection proc
-    # @return [void]
     def initialize(proc)
       @proc = proc
     end
 
     # Invokes the exception by calling the associated proc.
-    #
-    # @return [void]
     def invoke
       @proc.call
     end

data/lib/polyphony/core/sync.rb

@@ -27,7 +27,7 @@ module Polyphony
     # Conditionally releases the mutex. This method is used by condition
     # variables.
     #
-    # @return [void]
+    # @return [nil]
     def conditional_release
       @store << @token
       @token = nil
@@ -37,7 +37,7 @@ module Polyphony
     # Conditionally reacquires the mutex. This method is used by condition
     # variables.
     #
-    # @return [void]
+    # @return [Fiber] current fiber
     def conditional_reacquire
       @token = @store.shift
       @holding_fiber = Fiber.current
@@ -140,7 +140,7 @@ module Polyphony
     #
     # @param mutex [Polyphony::Mutex] mutex to release while waiting for signal
     # @param _timeout [Number, nil] timeout in seconds (currently not implemented)
-    # @return [void]
+    # @return [any]
     def wait(mutex, _timeout = nil)
       mutex.conditional_release
       @queue << Fiber.current
@@ -151,7 +151,7 @@ module Polyphony
     # Signals the condition variable, causing the first fiber in the waiting
     # queue to be resumed.
     #
-    # @return [void]
+    # @return [Fiber] resumed fiber
     def signal
       return if @queue.empty?
 
@@ -160,8 +160,6 @@ module Polyphony
     end
 
     # Resumes all waiting fibers.
-    #
-    # @return [void]
     def broadcast
       return if @queue.empty?
 

data/lib/polyphony/core/thread_pool.rb

@@ -20,7 +20,7 @@ module Polyphony
 
     # Resets the default thread pool.
     #
-    # @return [void]
+    # @return [nil]
     def self.reset
       return unless @default_pool
 
@@ -78,8 +78,6 @@ module Polyphony
     private
 
     # Runs a processing loop on a worker thread.
-    #
-    # @return [void]
     def thread_loop
       while true
         run_queued_task
@@ -87,8 +85,6 @@ module Polyphony
     end
 
     # Runs the first queued task in the task queue.
-    #
-    # @return [void]
     def run_queued_task
       (block, watcher) = @task_queue.shift
       result = block.()

data/lib/polyphony/core/timer.rb

@@ -28,7 +28,6 @@ module Polyphony
     # Sleeps for the given duration.
     #
     # @param duration [Number] sleep duration in seconds
-    # @return [void]
     def sleep(duration)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -56,7 +55,6 @@ module Polyphony
     # consecutive iterations.
     #
     # @param interval [Number] interval between consecutive iterations in seconds
-    # @return [void]
     def every(interval)
       fiber = Fiber.current
       @timeouts[fiber] = {
@@ -180,8 +178,6 @@ module Polyphony
     end
 
     # Resets the timeout for the current fiber.
-    #
-    # @return [void]
     def reset
       record = @timeouts[Fiber.current]
       return unless record
@@ -216,8 +212,6 @@ module Polyphony
     end
 
     # Runs a timer iteration, invoking any timeouts that are due.
-    #
-    # @return [void]
     def update
       return if @timeouts.empty?
 

data/lib/polyphony/extensions/fiber.rb

@@ -213,7 +213,6 @@ class ::Fiber
   # @option opts [Proc, nil] :on_done proc to call when a supervised fiber is terminated
   # @option opts [Proc, nil] :on_error proc to call when a supervised fiber is terminated with an exception
   # @option opts [:always, :on_error, nil] :restart whether to restart terminated fibers
-  # @return [void]
   def supervise(*fibers, **opts, &block)
     block ||= supervise_opts_to_block(opts)
 
@@ -375,7 +374,7 @@ class ::Fiber
   # @param block [Proc] fiber's block
   # @param caller [Array<String>] fiber's caller
   # @param parent [Fiber] fiber's parent
-  # @return [void]
+  # @return [Fiber] self
   def prepare(tag, block, caller, parent)
     @thread = Thread.current
     @tag = tag
@@ -384,12 +383,13 @@ class ::Fiber
     @block = block
     Thread.backend.trace(:spin, self, Kernel.caller[1..-1])
     schedule
+    self
   end
 
   # Runs the fiber's block and handles uncaught exceptions.
   #
   # @param first_value [any] value passed to fiber on first resume
-  # @return [void]
+  # @return [any] fiber result
   def run(first_value)
     Kernel.raise first_value if first_value.is_a?(Exception)
     @running = true
@@ -397,6 +397,7 @@ class ::Fiber
     Thread.backend.trace(:unblock, self, first_value, @caller)
     result = @block.(first_value)
     finalize(result)
+    result
   rescue Polyphony::Restart => e
     restart_self(e.value)
   rescue Polyphony::MoveOn, Polyphony::Terminate => e
@@ -411,27 +412,29 @@ class ::Fiber
   # fiber terminates after it has already been created. Calling #setup_raw
   # allows the fiber to be scheduled and to receive messages.
   #
-  # @return [void]
+  # @return [Fiber] self
   def setup_raw
     @thread = Thread.current
     @running = true
+    self
   end
 
   # Sets up the fiber as the main fiber for the current thread.
   #
-  # @return [void]
+  # @return [Fiber] self
   def setup_main_fiber
     @main = true
     @tag = :main
     @thread = Thread.current
     @running = true
     @children&.clear
+    self
   end
 
   # Resets the fiber's state and reruns the fiber.
   #
   # @param first_value [Fiber] first_value to pass to fiber after restarting
-  # @return [void]
+  # @return [any] fiber result
   def restart_self(first_value)
     @mailbox = nil
     run(first_value)
@@ -441,7 +444,7 @@ class ::Fiber
   #
   # @param result [any] return value
   # @param uncaught_exception [Exception, nil] uncaught exception
-  # @return [void]
+  # @return [false]
   def finalize(result, uncaught_exception = false)
     result, uncaught_exception = finalize_children(result, uncaught_exception)
     Thread.backend.trace(:terminate, self, result)
@@ -462,7 +465,7 @@ class ::Fiber
   #
   # @param result [any] fiber's return value
   # @param uncaught_exception [Exception, nil] uncaught exception
-  # @return [void]
+  # @return [Array] array containing result and uncaught exception if any
   def finalize_children(result, uncaught_exception)
     shutdown_all_children(graceful_shutdown?)
     [result, uncaught_exception]
@@ -474,7 +477,7 @@ class ::Fiber
   #
   # @param result [any] fiber's return value
   # @param uncaught_exception [Exception, nil] uncaught exception
-  # @return [void]
+  # @return [Fiber] self
   def inform_monitors(result, uncaught_exception)
     if @monitors
       msg = [self, result]
@@ -485,6 +488,8 @@ class ::Fiber
       parent_is_monitor = @monitors&.has_key?(@parent)
       @parent.schedule_with_priority(result) unless parent_is_monitor
     end
+
+    self
   end
 
   # Adds a fiber to the list of monitoring fibers. Monitoring fibers will be
@@ -598,8 +603,6 @@ class ::Fiber
     # running, it will bubble up to the main thread's main fiber, which will
     # also be scheduled with priority. This method is mainly used trapping
     # signals (see also the patched `Kernel#trap`)
-    #
-    # @return [void]
     def schedule_priority_oob_fiber(&block)
       oob_fiber = Fiber.new do
         Fiber.current.setup_raw

data/lib/polyphony/extensions/io.rb

@@ -355,7 +355,7 @@ class ::IO
   #
   # @param maxlen [Integer] maximum bytes to receive
   # @yield [String] read data
-  # @return [void]
+  # @return [IO] self
   def read_loop(maxlen = 8192, &block)
     Polyphony.backend_read_loop(self, maxlen, &block)
   end
@@ -376,7 +376,7 @@ class ::IO
   #
   # @param receiver [any] receiver object
   # @param method [Symbol] method to call
-  # @return [void]
+  # @return [IO] self
   def feed_loop(receiver, method = :call, &block)
     Polyphony.backend_feed_loop(self, receiver, method, &block)
   end