Project

nursery

0.0
No commit activity in last 3 years
No release in over 3 years
A simple API for asynchronous flow control to make it clear when jobs finish.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Development

~> 1.16
~> 10.0
~> 3.0
 Project Readme

Nursery

Notes on structured concurrency, or: Go statement considered harmful argues for a specific pattern for asynchronous operations: nurseries. A nursery is created within a code block and can spawn children that run asynchronous tasks that are guaranteed to be complete by the time the code block ends, no matter how much indirection you're using. The nursery pattern is implemented in the Python library Trio.

If this pattern takes over the world, we'll need it in Ruby too. This gem implements the Nursery pattern at a high level. By default it uses Ruby's native concurrency handling.

Installation

Add this line to your application's Gemfile:

gem 'nursery'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nursery

Usage

See the specs for code samples (excerpts below) or USAGE_GUIDE.md for a quick guide.

describe "simple parallelism" do

	it "runs blocks in parallel" do
		start_time = Time.now

		Nursery.with_nursery do |nursery|

			20.times { nursery.run { sleep(0.1) } }

		end

		expect(Time.now).to be_within(0.2).of(start_time)
	end

	it "can share state naively (but probably shouldn't)" do

		numbers = []

		Nursery.with_nursery do |nursery|

			1.upto(10) do |i|
				nursery.run do
					numbers << i
				end
			end
		end

		expect(numbers).to match_array( [*1..10].shuffle )

	end

	it "lets siblings cancel siblings" do

		numbers = [1,2,3]		

		Nursery.with_nursery do |nursery|

			nursery.run { loop { do_something_expensive; Nursery.checkpoint } }

			nursery.run { do_something_expensive; numbers.clear; nursery.cancel }
		end

		expect(numbers).to be_empty

	end

	it "lets siblings refer to each other" do
		Nursery.with_nursery do |nursery|

			values = [0, 1, 0, 0, 2, 5, 6]

			cleaner = nursery.run do
				values.reject! { |i| sleep(0.1); i.zero? }
			end

			nursery.run do
				sum = values.inject(:+)
				cleaner.finish
				values.each { |x| sum += 1.0/x }
				expect(15..16).to cover(sum)
			end

		end
	end

	it "ensures no task runs after the block finishes" do
		state_leaker = {}

		Nursery.with_nursery do |nursery|

			state_leaker[:nursery] = nursery
		
		end

		expect{ state_leaker[:nursery].run{ do_something_expensive } }
			.to raise_exception(RuntimeError, "Nursery#run called outside of with_nursery block")

	end

end

describe "composing with other patterns" do

	class AsyncBuilder

		attr_reader :nursery
		attr_accessor :attributes

		def initialize(nursery, &block)
			@nursery = nursery
			@attributes = {}
			instance_exec(&block)
		end

		def convert_to_value(*values)
			do_something_expensive
			values.join
		end

		def method_missing(m,*args,&block)
			nursery.run { attributes[m] = convert_to_value(*args) }
		end

	end

	it "plays well with instance_exec" do

		builder_obj = Nursery.with_nursery do |nursery|

			thing = 0

			AsyncBuilder.new(nursery) do

				llama 				:hairy
				other_llama			:hairier
				third_llama			:shorn
				thing				thing
			end

		end

		expect(builder_obj.attributes).to eq ( {llama: 'hairy', other_llama: 'hairier', third_llama: 'shorn', thing: '0'} )
	end

end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/histocrat/nursery. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Nursery project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.