polyphony 0.99.4 → 0.99.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd44b14a67b4f5aedd2f46010ff0ca790072f7c5261c6b6c53b622667264cec9
-  data.tar.gz: 9bcc853cbbb8f03e4fc7370b957f5895d78f36fece297d130451d8fef37da782
+  metadata.gz: 4a2733c956cab37dac192c107c4c2def808595601cca177dfbfcbd23b3b291e7
+  data.tar.gz: 417aacff2dac6ec2f4cfe85c8afc0bab21a5d20ac8748a3a5ceca42ec7950b8c
 SHA512:
-  metadata.gz: 226dc8b0f9d8b0599df1444b0f8c3dd99c8fad7484a7c6cf9d4cc25e136d25cce33c56632f3c0e823216e76f21ab2ff06ff4d629e67134592302b85b95967e00
-  data.tar.gz: c277e9f9ac12001b7b30584e97e67020b9cc6088525249386868a783f0e38a8c88fbaa852ec36246d28a44d7f4cb93c9aaffa7ddfb8c1bca8396f80b569a63ff
+  metadata.gz: 7c5d41ad9927a1b3770b76b702bc3f7695d4fb0c87601df3a5fd9d25cdc3e121881ec4e9dbbe618234864c73b8ac67cf1f9156a5bc031a7186d9633a03d70e00
+  data.tar.gz: ad66aab4d2fb6b60f702791036fa8883b6e262eadee7170dc285d68903b2447d17160aec9e382c336ace24e3e0379d25683ba736084df6c61c36858b465513e4

data/.rubocop.yml

@@ -85,6 +85,7 @@ Metrics/MethodLength:
   Exclude:
     - lib/polyphony/http/server/rack.rb
     - lib/polyphony/extensions/io.rb
+    - lib/polyphony/extensions/fiber.rb
     - test/**/*.rb
     - examples/**/*.rb
 
@@ -97,9 +98,19 @@ Metrics/ClassLength:
   Exclude:
     - 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
 
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - lib/polyphony/extensions/fiber.rb
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - lib/polyphony/extensions/fiber.rb
+
 Style/RegexpLiteral:
   Enabled: false
 

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/examples/pipes/gzip_http_server.rb

@@ -13,14 +13,14 @@ require 'h1p'
 def handle_client(conn)
   spin do
     parser = H1P::Parser.new(conn, :server)
-    
+
     while true # assuming persistent connection
       headers = parser.parse_headers
       break unless headers
 
       raw_buffer = Polyphony.pipe
       gzip_buffer = Polyphony.pipe
-      
+
       # splice request body to buffer
       spin do
         parser.splice_body_to(raw_buffer)

data/examples/pipes/http_server.rb

@@ -14,7 +14,7 @@ require 'h1p'
 def handle_client(conn)
   spin do
     parser = H1P::Parser.new(conn, :server)
-    
+
     while true # assuming persistent connection
       headers = parser.parse_headers
       break unless headers

data/examples/pipes/tcp_proxy.rb

@@ -10,7 +10,7 @@ def handle_client(conn)
     dest = TCPSocket.new(*DESTINATION)
     # w_buffer = Polyphony.pipe
     # r_buffer = Polyphony.pipe
-    
+
     # spin { IO.splice(conn, w_buffer, -1000) }
     # spin { IO.splice(w_buffer, dest, -1000) }
 

data/ext/polyphony/backend_common.c

@@ -280,14 +280,14 @@ inline VALUE backend_snooze(struct Backend_base *backend) {
   VALUE ret;
   VALUE fiber = rb_fiber_current();
   VALUE thread = rb_thread_current();
-  
+
   CHECK_FIBER_THREAD_REF(fiber, thread);
-  
+
   Fiber_make_runnable(fiber, Qnil);
   ret = Thread_switch_fiber(thread);
 
   COND_TRACE(backend, 4, SYM_unblock, fiber, ret, CALLER());
-  
+
   return ret;
 }
 
@@ -306,7 +306,7 @@ inline double current_time(void) {
   struct timespec ts;
   double t;
   uint64_t ns;
-  
+
   clock_gettime(CLOCK_MONOTONIC, &ts);
   ns = ts.tv_sec;
   ns = ns * 1e9 + ts.tv_nsec;

data/ext/polyphony/backend_io_uring.c

@@ -101,7 +101,7 @@ static VALUE Backend_initialize(VALUE self) {
   while (1) {
     int ret = io_uring_queue_init(backend->prepared_limit, &backend->ring, flags);
     if (!ret) break;
-    
+
     // if ENOMEM is returned, use a smaller limit
     if (ret == -ENOMEM && backend->prepared_limit > 64)
       backend->prepared_limit = backend->prepared_limit / 2;
@@ -263,10 +263,10 @@ inline VALUE Backend_poll(VALUE self, VALUE blocking) {
   if (!is_blocking && backend->pending_sqes) io_uring_backend_immediate_submit(backend);
 
   COND_TRACE(&backend->base, 2, SYM_enter_poll, rb_fiber_current());
-  
+
   if (is_blocking) io_uring_backend_poll(backend);
   io_uring_backend_handle_ready_cqes(backend);
-  
+
   COND_TRACE(&backend->base, 2, SYM_leave_poll, rb_fiber_current());
 
   return self;
@@ -414,7 +414,7 @@ VALUE Backend_read(VALUE self, VALUE io, VALUE buffer, VALUE length, VALUE to_eo
     struct io_uring_sqe *sqe = io_uring_backend_get_sqe(backend);
     int result;
     int completed;
-    
+
     io_uring_prep_read(sqe, fd, buffer_spec.ptr, buffer_spec.len, -1);
 
     result = io_uring_backend_defer_submit_and_await(backend, sqe, ctx, &resume_value);
@@ -449,7 +449,7 @@ VALUE Backend_read(VALUE self, VALUE io, VALUE buffer, VALUE length, VALUE to_eo
   }
 
   if (!total) return Qnil;
-  
+
   if (!buffer_spec.raw) backend_finalize_string_buffer(buffer, &buffer_spec, total, fptr);
   return buffer_spec.raw ? INT2FIX(total) : buffer;
 }
@@ -1412,7 +1412,7 @@ int io_uring_backend_submit_timeout_and_await(Backend_t *backend, double duratio
   struct __kernel_timespec ts = double_to_timespec(duration);
   struct io_uring_sqe *sqe = io_uring_backend_get_sqe(backend);
   op_context_t *ctx = context_store_acquire(&backend->store, OP_TIMEOUT);
-  
+
   io_uring_prep_timeout(sqe, &ts, 0, 0);
   io_uring_backend_defer_submit_and_await(backend, sqe, ctx, resume_value);
   return context_store_release(&backend->store, ctx);
@@ -1723,7 +1723,7 @@ VALUE Backend_chain(int argc,VALUE *argv, VALUE self) {
   completed = context_store_release(&backend->store, ctx);
   if (!completed) {
     struct io_uring_sqe *sqe;
-    
+
     Backend_chain_ctx_attach_buffers(ctx, argc, argv);
 
     // op was not completed (an exception was raised), so we need to cancel it
@@ -1793,7 +1793,7 @@ static inline void splice_chunks_get_sqe(
 
 static inline void splice_chunks_cancel(Backend_t *backend, op_context_t *ctx) {
   struct io_uring_sqe *sqe;
-  
+
   ctx->result = -ECANCELED;
   sqe = io_uring_backend_get_sqe(backend);
   io_uring_prep_cancel(sqe, ctx, 0);

data/ext/polyphony/backend_libev.c

@@ -169,14 +169,14 @@ inline VALUE Backend_poll(VALUE self, VALUE blocking) {
   backend->base.poll_count++;
 
   COND_TRACE(&backend->base, 2, SYM_enter_poll, rb_fiber_current());
-  
+
 ev_run:
   backend->base.currently_polling = 1;
   errno = 0;
   ev_run(backend->ev_loop, blocking == Qtrue ? EVRUN_ONCE : EVRUN_NOWAIT);
   backend->base.currently_polling = 0;
   if (errno == EINTR && runqueue_empty_p(&backend->base.runqueue)) goto ev_run;
-  
+
   COND_TRACE(&backend->base, 2, SYM_leave_poll, rb_fiber_current());
 
   return self;
@@ -335,7 +335,7 @@ VALUE Backend_read(VALUE self, VALUE io, VALUE buffer, VALUE length, VALUE to_eo
   }
 
   if (!total) return Qnil;
-  
+
   if (!buffer_spec.raw) backend_finalize_string_buffer(buffer, &buffer_spec, total, fptr);
 
   RB_GC_GUARD(watcher.fiber);
@@ -359,7 +359,7 @@ VALUE Backend_recvmsg(VALUE self, VALUE io, VALUE buffer, VALUE maxlen, VALUE po
   struct backend_buffer_spec buffer_spec = backend_get_buffer_spec(buffer, 0);
   long total = 0;
   VALUE switchpoint_result = Qnil;
-  
+
   GetBackend(self, backend);
   backend_prepare_read_buffer(buffer, maxlen, &buffer_spec, FIX2INT(pos));
   fd = fd_from_io(io, &fptr, 0, 1);
@@ -403,7 +403,7 @@ VALUE Backend_recvmsg(VALUE self, VALUE io, VALUE buffer, VALUE maxlen, VALUE po
   }
 
   if (!total) return Qnil;
-  
+
   if (!buffer_spec.raw) backend_finalize_string_buffer(buffer, &buffer_spec, total, fptr);
   VALUE addr = name_to_addrinfo(msg.msg_name, msg.msg_namelen);
   VALUE rflags = INT2NUM(msg.msg_flags);

data/ext/polyphony/fiber.c

@@ -60,13 +60,14 @@ inline void Fiber_make_runnable_with_priority(VALUE fiber, VALUE value) {
   Thread_schedule_fiber_with_priority(thread, fiber, value);
 }
 
-/* call-seq:
- *   fiber.schedule
- *   fiber.schedule(value)
- * 
- * Adds the fiber to the runqueue with the given resume value or `nil`.
- * 
- * @return [void]
+/* Adds the fiber to the runqueue with the given resume value. If no resume
+ * value is given, the fiber will be resumed with `nil`.
+ *
+ * @overload schedule(value)
+ *   @param value [any] resume value
+ *   @return [Fiber] scheduled fiber
+ * @overload schedule
+ *   @return [Fiber] scheduled fiber
  */
 
 static VALUE Fiber_schedule(int argc, VALUE *argv, VALUE self) {
@@ -75,14 +76,14 @@ static VALUE Fiber_schedule(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
-/* call-seq:
- *   fiber.schedule_with_priority
- *   fiber.schedule_with_priority(value)
- * 
- * Adds the fiber to the head of the runqueue with the given resume value or
- * `nil`.
- * 
- * @return [void]
+/* Adds the fiber to the head of the runqueue with the given resume value. If no
+ * resume value is given, the fiber will be resumed with `nil`.
+ *
+ * @overload schedule_with_priority(value)
+ *   @param value [any] resume value
+ *   @return [Fiber] scheduled fiber
+ * @overload schedule_with_priority
+ *   @return [Fiber] scheduled fiber
  */
 
 static VALUE Fiber_schedule_with_priority(int argc, VALUE *argv, VALUE self) {
@@ -91,12 +92,14 @@ static VALUE Fiber_schedule_with_priority(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
-/* call-seq:
- *   fiber.state -> sym
- * 
- * Returns the current state for the fiber, one of `:running`, `:runnable`,
- * `:waiting`, `:dead`.
- * 
+/* Returns the current state for the fiber, one of the following:
+ *
+ * - `:running` - the fiber is currently running.
+ * - `:runnable` - the fiber is on the runqueue, scheduled to be resumed ("ran").
+ * - `:waiting` - the fiber is waiting on some blocking operation to complete,
+ *   allowing other fibers to run.
+ * - `:dead` - the fiber has finished running.
+ *
  * @return [Symbol]
  */
 
@@ -109,14 +112,11 @@ static VALUE Fiber_state(VALUE self) {
   return SYM_waiting;
 }
 
-/* call-seq:
- *   fiber.send(msg)
- * 
- * Sends a message to the given fiber. The message will be added to the fiber's
+/* Sends a message to the given fiber. The message will be added to the fiber's
  * mailbox.
- * 
+ *
  * @param msg [any]
- * @return [void]
+ * @return [Fiber] self
  */
 
 VALUE Fiber_send(VALUE self, VALUE msg) {
@@ -129,12 +129,9 @@ VALUE Fiber_send(VALUE self, VALUE msg) {
   return self;
 }
 
-/* call-seq:
- *   fiber.receive -> msg
- * 
- * Receive's a message from the fiber's mailbox. If no message is available,
+/* Receive's a message from the fiber's mailbox. If no message is available,
  * waits for a message to be sent to it.
- * 
+ *
  * @return [any] received message
  */
 
@@ -147,11 +144,8 @@ VALUE Fiber_receive(VALUE self) {
   return Queue_shift(0, 0, mailbox);
 }
 
-/* call-seq:
- *   fiber.mailbox -> queue
- * 
- * Returns the fiber's mailbox.
- * 
+/* Returns the fiber's mailbox.
+ *
  * @return [Queue]
  */
 
@@ -164,11 +158,8 @@ VALUE Fiber_mailbox(VALUE self) {
   return mailbox;
 }
 
-/* call-seq:
- *   fiber.receive_all_pending -> ary
- * 
- * Receives all messages currently in the fiber's mailbox.
- * 
+/* Receives all messages currently in the fiber's mailbox.
+ *
  * @return [Array]
  */
 

data/ext/polyphony/io_extensions.c

@@ -322,7 +322,7 @@ void read_gzip_header_str(struct buffer_spec *buffer_spec, VALUE *str, unsigned
   }
   if (null_pos == *total_read)
     rb_raise(rb_eRuntimeError, "Invalid gzip header");
-  
+
   *str = rb_str_new_cstr((char *)buffer_spec->ptr + *in_pos);
   *in_pos = null_pos + 1;
 }
@@ -507,14 +507,18 @@ static inline VALUE z_stream_cleanup(struct z_stream_ctx *ctx) {
 #define Z_STREAM_SAFE_IO_LOOP_WITH_CLEANUP(ctx) \
   rb_ensure(SAFE(z_stream_io_loop), (VALUE)&ctx, SAFE(z_stream_cleanup), (VALUE)&ctx)
 
-/* call-seq:
- *   IO.gzip(src, dest) -> bytes_written
- *   IO.gzip(src, dest, opt) -> bytes_written
- *
- * Gzips data from the source IO to the destination IO, returning the number
+/* Gzips data from the source IO to the destination IO, returning the number
  * bytes written to the destination IO.
- * 
- * @return [Integer]
+ *
+ * @overload gzip(src, dest)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @return [Integer]
+ * @overload gzip(src, dest, opt)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @param opt [Hash] gzip options
+ *   @return [Integer]
  */
 
 VALUE IO_gzip(int argc, VALUE *argv, VALUE self) {
@@ -542,20 +546,24 @@ VALUE IO_gzip(int argc, VALUE *argv, VALUE self) {
   ret = deflateInit2(&ctx.strm, DEFAULT_LEVEL, Z_DEFLATED, -MAX_WBITS, DEFAULT_MEM_LEVEL, Z_DEFAULT_STRATEGY);
   if (ret != Z_OK)
     rb_raise(rb_eRuntimeError, "zlib error: %s\n", ctx.strm.msg);
-  Z_STREAM_SAFE_IO_LOOP_WITH_CLEANUP(ctx); 
+  Z_STREAM_SAFE_IO_LOOP_WITH_CLEANUP(ctx);
   return INT2FIX(ctx.out_total);
 }
 
 # define FIX2TIME(v) (rb_funcall(rb_cTime, ID_at, 1, v))
 
-/* call-seq:
- *   IO.gunzip(src, dest) -> bytes_written
- *   IO.gunzip(src, dest, opt) -> bytes_written
- *
- * Gunzips data from the source IO to the destination IO, returning the number
+/* Gunzips data from the source IO to the destination IO, returning the number
  * bytes written to the destination IO.
- * 
- * @return [Integer]
+ *
+ * @overload gunzip(src, dest)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @return [Integer]
+ * @overload gunzip(src, dest, opt)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @param opt [Hash] gzip options
+ *   @return [Integer]
  */
 
 VALUE IO_gunzip(int argc, VALUE *argv, VALUE self) {
@@ -594,14 +602,18 @@ VALUE IO_gunzip(int argc, VALUE *argv, VALUE self) {
   return INT2FIX(ctx.out_total);
 }
 
-/* call-seq:
- *   IO.deflate(src, dest) -> bytes_written
- *   IO.deflate(src, dest, opt) -> bytes_written
- *
- * Defaltes data from the source IO to the destination IO, returning the number
+/* Deflates data from the source IO to the destination IO, returning the number
  * bytes written to the destination IO.
- * 
- * @return [Integer]
+ *
+ * @overload deflate(src, dest)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @return [Integer]
+ * @overload deflate(src, dest, opt)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @param opt [Hash] gzip options
+ *   @return [Integer]
  */
 
 VALUE IO_deflate(VALUE self, VALUE src, VALUE dest) {
@@ -615,18 +627,22 @@ VALUE IO_deflate(VALUE self, VALUE src, VALUE dest) {
     rb_raise(rb_eRuntimeError, "zlib error: %s\n", ctx.strm.msg);
 
   Z_STREAM_SAFE_IO_LOOP_WITH_CLEANUP(ctx);
- 
+
   return INT2FIX(ctx.out_total);
 }
 
-/* call-seq:
- *   IO.inflate(src, dest) -> bytes_written
- *   IO.inflate(src, dest, opt) -> bytes_written
- *
- * Inflates data from the source IO to the destination IO, returning the number
+/* Inflates data from the source IO to the destination IO, returning the number
  * bytes written to the destination IO.
- * 
- * @return [Integer]
+ *
+ * @overload inflate(src, dest)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @return [Integer]
+ * @overload inflate(src, dest, opt)
+ *   @param src [IO, Polyphony::Pipe] source IO
+ *   @param dest [IO, Polyphony::Pipe] destination IO
+ *   @param opt [Hash] gzip options
+ *   @return [Integer]
  */
 
 VALUE IO_inflate(VALUE self, VALUE src, VALUE dest) {
@@ -639,17 +655,14 @@ VALUE IO_inflate(VALUE self, VALUE src, VALUE dest) {
     rb_raise(rb_eRuntimeError, "zlib error: %s\n", ctx.strm.msg);
 
   Z_STREAM_SAFE_IO_LOOP_WITH_CLEANUP(ctx);
- 
+
   return INT2FIX(ctx.out_total);
 }
 
-/* call-seq:
- *   IO.http1_splice_chunked(src, dest, maxlen)
- *
- * Splices data from the source IO to the destination IO, writing it in HTTP1
+/* Splices data from the source IO to the destination IO, writing it in HTTP1
  * chunked encoding. A pipe is automatically created to buffer data between
  * source and destination.
- * 
+ *
  * @param src [IO] source
  * @param dest [IO] destination
  * @param maxlen [Integer] maximum bytes to splice

data/ext/polyphony/pipe.c

@@ -36,12 +36,7 @@ static VALUE Pipe_allocate(VALUE klass) {
 #define GetPipe(obj, pipe) \
   TypedData_Get_Struct((obj), Pipe_t, &Pipe_type, (pipe))
 
-/* call-seq:
- *   Pipe.new -> pipe
- *
- * Creates a new pipe.
- * 
- * @return [void]
+/* Creates a new pipe.
  */
 
 static VALUE Pipe_initialize(VALUE self) {
@@ -80,11 +75,8 @@ int Pipe_get_fd(VALUE self, int write_mode) {
   return pipe->fds[write_mode ? 1 : 0];
 }
 
-/* call-seq:
- *   pipe.closed? -> bool
+/* Returns true if the pipe is closed.
  *
- * Returns true if the pipe is closed.
- * 
  * @return [boolean]
  */
 
@@ -94,11 +86,8 @@ VALUE Pipe_closed_p(VALUE self) {
   return pipe->w_closed ? Qtrue : Qfalse;
 }
 
-/* call-seq:
- *   pipe.close -> pipe
+/* Closes the pipe.
  *
- * Closes the pipe.
- * 
  * @return [Pipe] self
  */
 
@@ -113,12 +102,9 @@ VALUE Pipe_close(VALUE self) {
   return self;
 }
 
-/* call-seq:
- *   Pipe.fds -> [r, w]
- *
- * Returns an array containing the read and write fds for the pipe,
+/* Returns an array containing the read and write fds for the pipe,
  * respectively.
- * 
+ *
  * @return [Array<Integer>]
  */
 
@@ -131,7 +117,7 @@ VALUE Pipe_fds(VALUE self) {
 
 void Init_Pipe(void) {
   cPipe = rb_define_class_under(mPolyphony, "Pipe", rb_cObject);
-  
+
   /*
    * Document-class: Polyphony::Pipe::ClosedPipeError
    *