class Bonito::SerialTimeline

A SerialTimeline is a data structure with a duration (measured in seconds) that contains timelines. A timeline is any instance of a class that inherits from the Timeline base class.

A SerialTimeline serves to define an interval in which it may be simulated that one or more Moment objects are evaluated in series_.

A SerialTimeline exposes methods that can either be used to define these Moment objects directly or to create additional child data structures (i.e ParallelTimeline objects or further, child SerialTimeline objects) which can in turn be provide more fine grained control over precisely when any given Moment objects may be evaluated.

Example¶ ↑

Bonito.over(2.weeks) do
  please { puts Time.now }
end

The above defines a SerialTimeline (using the Bonito#over module method) that specifies a 2 week time period. A single Moment is included in this serial (via the please factory method). When the top level SerialTimeline is evaluated (using a Runner object) the block

puts Time.now

is evaluated exactly once. Furthermore, the simulated time at which the block is evaluated will be contained at some point within the 2 week interval beginning on some start date provided when instantiating the Runner object.

As mentioned, it is also possible to include other data structures within SerialTimeline objects, including other SerialTimeline objects.

Example¶ ↑

We could use the over method to add an empty SerialTimeline to the previous example in order to force the already included Moment to be evaluated during the last day of the 2 week period.

Bonito.over(2.weeks) do
  over(2.weeks - 1.day)  # This defines an empty serial
  please { puts Time.now }
end

The empty SerialTimeline returned by the over factory method consumes 13 days of the parent SerialTimeline object's total duration of 2 weeks. This means that when this parent SerialTimeline is evaluated, the Moment will be as if it occurred during the final day of the 2 week period.

Finally, we may also define ParallelTimeline objects within serials using the simultaneously method. These allow for multiple SerialTimeline objects to be defined over the same time period and for any Moment objects contained within to be interleaved when the parent SerialTimeline is ultimately evaluated.

The simultaneously method instantiates a ParallelTimeline object, whilst accepting a block. The block is evaluated within the context of the new ParallelTimeline. Timelines defined within this block will be evaluated in parallel.

Note that ParallelTimeline implements many of the same methods as SerialTimeline

Example¶ ↑

Bonito.over(2.weeks) do
  simultaneously do
    over 1.week do
      puts "SerialTimeline 1 #{Time.now}"
    end
    over 6.days, after: 1.day do
      puts "SerialTimeline 2 #{Time.now}"
    end
  end

  over 1.week {}  # This defines an empty serial
end

Now, when evaluating this SerialTimeline both the blocks

puts "SerialTimeline 1 #{Time.now}"

and

puts "SerialTimeline 2 #{Time.now}"

will be evaluated once during the first week. The precise instant is chosen randomly within this interval with the only constraint being that the second block cannot be evaluated during the first day (This offset is controlled by the after parameter of the simultaneously method).

Note that the moment from the second SerialTimeline could still be evaluated at a simulated time before that at which the moment from the first SerialTimeline is evaluated.