nursery

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

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

See other specs for more usage examples.

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/[USERNAME]/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.