fibril 0.0.1 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cf7d153b66e754a9c54176ad4aed2f7b6e5b0055
-  data.tar.gz: 57d3036405946c6c82bfce1cea816c119d5f71fd
+  metadata.gz: d3e934a87b86d8c9cd7be5ed5a25a367bb137ce2
+  data.tar.gz: 55d5321199638e5548ae4d05dd77c368278cef2d
 SHA512:
-  metadata.gz: 75bb606b9261c086109e971235f29fc624371db80f428e653b9918766d2346f674b4ce03e1a16ebb76239c8e22377a37b9a4b5ab3ef6e2b433eb5717f06b6479
-  data.tar.gz: d104f2d54afe2eeef3da5caae50b4d782576b7bb396caca58fd0986213c29eb0d9c87a45ce5844f3630b43dc5d67037546ba6d2ab5d1d9546af3ad5d1da47e96
+  metadata.gz: b462c4ed53203e9ee173d8267c5db43e9e53546da210dc9988b8c87e7ddcb746dd08970c4b2a7e90fdd8f1a5b84e1a697423de4f26a4296d61981015b86e80f9
+  data.tar.gz: ca8cb1567003a08491489f3503e3c88b494a6b1ee662a6a435881e69210d5e56ed8d8a1da8761fd8b0c0c99fae47de167eb0acac841078339f33409db161245b

data/README.md

@@ -1,5 +1,23 @@
 # Fibril
 
+Fibril is a pure Ruby library that allows you to use cooperative multitasking inside your Ruby code. It is a similar concept to the event loop in JavaScript, but makes use of context switching through Fibers to prevent the need for callback functions or promises.
+
+Traditionally you might approach concurrency in Ruby through the use of threads combined with concurrency primitives to synchronise critical sections of your code. Fibril takes an alternative approach where instead everything is synchronous and safe from concurrent state mutations unless explicitly told otherwise.
+
+You can use Fibril to yield from a flow of execution while waiting on an asychrouous call and fibril will schedule the same flow to resume as soon the asynchronous call is complete. All without the need for callbacks.
+
+You can be explicit in how you weave your fibrils together to ensure the order in which your multiple tasks execute is deterministic.
+
+## Why is it useful?
+You may be interested in Fibril if:
+* Your code has many fast operations that are often blocked by slow operations
+* You want to use two or more Ruby libraries which require a blocking IO loop together.
+* You have multiple IO operations that you wish to execute in parallel while ensuring the rest of your code executes synchronously
+* You want to manipulate multiple streams of data in parallel without having to worry about synchronisation across threads.
+
+In scenarios where many IO bound operations are the performance bottleneck of your application Fibril is likely to provide performance benefits. In other scenarios performance should be comparable to that using threads or executing all tasks synchronously.
+
+At its simplest Fibril will allow you to write source code that looks shallow and linear while allowing multiple flows of execution to complete concurrently.
 
 ## Installation
 
@@ -19,7 +37,7 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Read the wiki [here](https://github.com/wouterken/Fibril/wiki) and examine the [examples](https://github.com/wouterken/Fibril/tree/master/examples) in this repository to learn how to use Fibril.
 
 ## Development
 
@@ -29,8 +47,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fibril.
-
+Bug reports and pull requests are welcome on GitHub at https://github.com/wouterken/fibril.
 
 ## License
 

data/examples/example_async.rb

@@ -1,27 +1,13 @@
-require_relative "../lib/fibril/loop"
+require "fibril/loop"
 
 fibril{
-[1,2,3].async.each do |i|
-  puts i
-end
+  [1,3,5].each do |i|
+    async.print "#{i}:"
+  end
 }
 
 fibril{
-[4,5,6].async.each do |i|
-  puts i
-end
+  [2,4,6].each do |i|
+    async.print "#{i}:"
+  end
 }
-# Kernel.send :alias_method, :old_puts, :puts
-# Fibril::async :puts
-
-# puts 1
-# puts 2
-# puts 3
-
-# puts 4
-# puts 5
-# puts 6
-
-# sleep
-
-# old_puts "Done!"

data/examples/example_coop_multi_tasking.rb

@@ -0,0 +1,33 @@
+require "fibril/loop"
+
+def long_running_task
+  sleep 1
+  puts "Part 1 of long running task"
+  Fibril.current.tick
+  sleep 1
+  puts "Part 2 of long running task"
+  Fibril.current.tick
+  sleep 1
+  puts "Part 3 of long running task"
+  Fibril.current.tick
+  sleep 1
+  puts "Part 4 of long running task"
+  Fibril.current.tick
+end
+
+fibril.long_running_task
+
+fibril(:short_task_one){
+  puts "I'm a short task"
+}
+
+fibril(:short_task_one){
+  puts "I'm also a short task"
+}
+
+await(:short_task_one){
+  fibril(:short_task_three){
+    puts "I'm a third short task"
+  }
+}
+

data/examples/example_enum_tick.rb

@@ -0,0 +1,9 @@
+require "fibril/loop"
+
+[1,3,5].each.fibril do |i|
+  print "#{i},"
+end
+
+[2,4,6].each.fibril do |i|
+  print "#{i},"
+end

data/examples/example_execution_order.rb

@@ -0,0 +1,14 @@
+require 'fibril/loop'
+
+fibril{
+  puts "I'm executed second"
+  fibril{
+    puts "I'm executed last"
+  }
+}
+
+fibril{
+  puts "I'm executed third"
+}
+
+puts "I'm executed first"

data/examples/example_future_async_await.rb

@@ -0,0 +1,22 @@
+require 'fibril/loop'
+
+pending  = future{ sleep 1; 3 }
+pending2 = future{ sleep 0.1; 4 }
+
+fibril{
+  puts "Enter First"
+  async.await(pending)
+  puts "Leave First"
+}
+
+fibril{
+  puts "Enter Second"
+  result = async.await_all pending, pending2
+  puts "Leave Second"
+}
+
+fibril{
+  puts "Enter Third"
+  async.await(pending2)
+  puts "Leave Third"
+}

data/examples/example_future_sync_await.rb

@@ -0,0 +1,23 @@
+require 'fibril/loop'
+
+pending  = future{ sleep 1; 3 }
+pending2 = future{ sleep 0.1; 4 }
+
+fibril{
+  puts "Enter First"
+  await(pending)
+  puts "Leave First"
+}
+
+fibril{
+  puts "Enter Second"
+  await pending
+  await pending2
+  puts "Leave Second"
+}
+
+fibril{
+  puts "Enter Third"
+  await(pending2)
+  puts "Leave Third"
+}

data/examples/example_guard.rb

@@ -1,15 +1,17 @@
-require_relative "../lib/fibril/loop"
+require 'fibril/loop'
 
 fibril{
-  variables.guard.await
+  puts "Waiting on below fibril"
+  await(guard.g1)
   puts "First finished"
 }
 
-variables.guard = fibril{
+guard.g1 = fibril{
   sleep 0.2
-  puts "Second finished"
-}.until{ true }
+  puts "Middle finished"
+}
 
-await(variables.guard){
-  puts "Guard depleted"
+puts "Waiting on above"
+await(guard.g1){
+  puts "Third finished"
 }

data/examples/example_guard2.rb

@@ -0,0 +1,19 @@
+require 'fibril/loop'
+
+fibril(:g1){
+  sleep 1
+  4
+}
+
+fibril(:g2){
+  5
+}
+
+fibril{
+  puts "Sum is " + (await(:g1) + await(:g2)).to_s
+  puts "Sum is " + (await(guard.g1) + await(guard.g2)).to_s
+}
+
+await(:g2){|res|
+  puts "g2 available immediately: #{res}"
+}

data/examples/example_guard3.rb

@@ -0,0 +1,46 @@
+require 'fibril/loop'
+
+[*0...10].tick(:result_one).map do |i|
+  print "Item-1-#{i}, "
+  i * 3
+end
+
+[*10...20].tick(:result_two).map do |i|
+  print "Item-2-#{i}, "
+  i * 11
+end
+
+ fibril(:result_three){
+  async.sleep 0.5
+  puts "Three finished"
+}
+
+await(guard.result_one, guard.result_two){
+  puts "\nSum guard one & two:"
+  puts (await guard.result_one).zip((await guard.result_two)).inject(:+).to_s
+  await(guard.result_three){
+    puts "Continued!"
+  }
+}
+
+await(guard.result_one){
+  puts "\nGuard one results:"
+  puts "#{await guard.result_one}"
+  puts "Guard two results: #{await guard.result_two}"
+}
+
+
+fibril{
+  res = await(guard.result_four, guard.result_five)
+  puts "Res is #{res}"
+}
+
+fibril(:result_four){
+  async.sleep 0.5
+  "hello"
+}
+
+fibril(:result_five){
+  async.sleep 0.1
+  "world"
+}

data/examples/example_http.rb

@@ -0,0 +1,60 @@
+require 'net/http'
+require 'fibril/loop'
+
+def get_response_code(url, async=false)
+  url = URI.parse(url)
+  req = Net::HTTP::Get.new(url.to_s)
+  res = async ?
+    Net::HTTP.async.start(url.host, url.port, use_ssl: true) {|http|
+      http.request(req)
+    }
+  : Net::HTTP.start(url.host, url.port, use_ssl: true) {|http|
+      http.request(req)
+    }
+  variables.http_response_code2 = res.code
+end
+
+
+starts = Time.now
+Fibril.profile(:sync_http){
+  get_response_code('https://www.google.com')
+  get_response_code('https://nz.news.yahoo.com/')
+  get_response_code('https://github.com')
+  get_response_code('https://www.engadget.com')
+}
+puts "Sync v1 took #{Time.now - starts}"
+
+part_one = fibril{
+  starts = Time.now
+  fibril(:google).get_response_code('https://www.google.com', true)
+  fibril(:engadget).get_response_code('https://www.engadget.com', true)
+  fibril(:yahoo).get_response_code('https://nz.news.yahoo.com/', true)
+  fibril(:github).get_response_code('https://github.com',true)
+
+  fibril{
+    puts "#{await(:google, :yahoo, :github, :engadget)}"
+    puts "Async v1 took #{Time.now - starts}"
+  }
+}
+
+await(part_one){
+  start2 = Time.now
+  fibril(:a_engadget){
+    async.get_response_code('https://www.engadget.com')
+  }
+  fibril(:a_google){
+    async.get_response_code('https://www.google.com')
+  }
+  fibril(:a_yahoo){
+    async.get_response_code('https://nz.news.yahoo.com/')
+  }
+  fibril(:a_github){
+    async.get_response_code('https://github.com')
+  }
+
+
+  await(:a_google, :a_yahoo, :a_github, :a_engadget){|google, yahoo, github, engadget|
+    puts "#{[google, yahoo, github, engadget]}"
+    puts "Async v2 took #{Time.now - start2}"
+  }
+}

data/examples/example_multiple_loops.rb

@@ -0,0 +1,78 @@
+require 'fibril/loop'
+require 'net/http'
+
+def print_inline(lines, clear=true)
+  puts lines
+  system("tput cuu #{lines.length}") if clear
+end
+
+###
+# Calculate fibonacci numbers up until a limit
+##
+fibril(:fibonacci) do
+  variables.fib0, variables.fib1 = variables.fib1 || 1, variables.fib0.to_i + (variables.fib1 || 1)
+end.until{ variables.fib0 > 1000_000_000_000_000_000_000 }
+
+
+###
+# Calculate primes up until a limit
+##
+fibril do
+  limit = 500
+  primes = [false] + ([true] * (limit - 1))
+  primes.each.with_index(1).tick(:primes).map do |prime, i|
+    prime ? (mult = i) : next
+    variables.prime = variables.prime ? variables.prime + ", #{i}" : "#{i}"
+    primes[(mult += i) - 1] = false while mult <= limit - i
+    variables.prime
+  end
+end
+
+##
+# Make an HTTP request
+##
+fibril(:http) do
+  url = URI.parse('http://www.example.com/index.html')
+  req = Net::HTTP::Get.new(url.to_s)
+  res = Net::HTTP.async.start(url.host, url.port) {|http|
+    http.request(req)
+  }
+  variables.http_response_code = res.code
+end
+
+##
+# Make an HTTP request
+##
+fibril(:http2) do
+  url = URI.parse('https://www.facebook.com')
+  req = Net::HTTP::Get.new(url.to_s)
+  res = Net::HTTP.async.start(url.host, url.port, use_ssl: true) {|http|
+    http.request(req)
+  }
+  variables.http_response_code2 = res.code
+end
+
+##
+# Print status of above currently executing fibrils above
+##
+fibril(:print_loop){
+  print_inline [
+    "Fibonacci: #{variables.fib1}",
+    "Prime: #{variables.prime.to_s[-18..-1]}",
+    "HTTP Response code (example.com): #{variables.http_response_code}",
+    "HTTP Response code (facebook.com): #{variables.http_response_code2}"
+  ]
+}.until(:fibonacci, :primes, :http)
+
+##
+# Print final result status after all fibrils have completed
+##
+await(:print_loop){
+  print_inline [
+    "Fibonacci: #{variables.fib1}",
+    "Prime: #{variables.prime.to_s[-18..-1]}",
+    "HTTP Response code (example.com): #{await :http}",
+    "HTTP Response code (facebook.com): #{await :http2}",
+    "Finished!"
+  ], false
+}

data/examples/example_redis.rb

@@ -0,0 +1,49 @@
+require 'fibril/loop'
+require 'redis'
+##
+# Example non blocking IO wrapper for Redis IO
+##
+class RedisPubSubWrapper < Fibril::NonBlockingIOWrapper
+  attr_accessor :pub, :sub, :channel_name
+
+  def initialize(channel_name)
+    self.channel_name = channel_name
+    self.pub, self.sub = Redis.new, Redis.new
+    super{ sub.subscribe(channel_name){|on| on.message(&receive) }}
+  end
+
+  def publish(msg)
+    pub.publish(channel_name, msg)
+  end
+end
+
+
+##
+#
+# Example:
+#
+##
+
+def publish(redis)
+  $total_invocation_count ||= 0
+  $total_invocation_count += 1
+  async.sleep 0.1
+  puts "SEND: #{"M1:I#{$total_invocation_count}"}"
+  redis.async.publish("M1:I#{$total_invocation_count}")
+  puts "SEND: #{"M2:I#{$total_invocation_count}"}"
+  redis.async.publish("M2:I#{$total_invocation_count}")
+  puts "SEND: #{"M3:I#{$total_invocation_count}"}"
+  redis.async.publish("M3:I#{$total_invocation_count}")
+end
+
+def recv(redis)
+  $total_recv_count ||= 0
+  $total_recv_count += 1
+  _channel, message = redis.await
+  puts "RECV: #{message}: total: #{$total_recv_count}"
+end
+
+redis = RedisPubSubWrapper.new 'test'
+fibril.publish(redis).loop(10)
+fibril.recv(redis).loop(30)
+