Class: TickTock::Clock

Inherits:
Object
  • Object
show all
Defined in:
lib/tick_tock/clock.rb,
lib/tick_tock/clock.rb

Overview

A Clock can #tick and then #tock. Inspired by the “punch-card” or “bundy” clock (where workers carry their own cards to punch in and out): the instances of Clock are immutable, and the states of timing contexts are kept on “cards”.

Punch cards

This class delegates to a Punch implementation (via #punch) in order to obtain cards, to punch them in, and to punch them out. It does not depend on any details of those classes. It is therefore possible to replace the implementation of Punch - for example, to provide an alternate time source, or to use a memory-optimized representation of the punch cards.

Hierarchical state

To represent the hierarchy of currently active punch cards, we use Locals, which allows us to get and set state in a manner analogous to thread-local variables, but which can be captured and accessed across asynchronous contexts.

Logging and any other side-effects

Callbacks #on_tick and #on_tock define logging (and any other ) side-effects) which should take place on ticks and tocks.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(punch, on_tick, on_tock) ⇒ Clock

Returns a new instance of Clock.

Parameters:

  • punch (Punch) —

    Implementation of Punch to use

  • on_tick (Proc, nil) —

    Callback on #tick

  • on_tock (Proc, nil) —

    Callback on #tock



13
 
# File 'lib/tick_tock/clock.rb', line 13

def initialize(punch, on_tick, on_tock); end

Instance Attribute Details

#on_tick ⇒ Proc? (readonly)

Callback on #tick

Returns:

  • (Proc, nil) —

    the current value of on_tick



1
2
3
 
# File 'lib/tick_tock/clock.rb', line 1

def on_tick
  @on_tick
end

#on_tock ⇒ Proc? (readonly)

Callback on #tock

Returns:

  • (Proc, nil) —

    the current value of on_tock



1
2
3
 
# File 'lib/tick_tock/clock.rb', line 1

def on_tock
  @on_tock
end

#punch ⇒ Punch (readonly)

Implementation of Punch to use

Returns:

  • (Punch) —

    the current value of punch



60
61
62
 
# File 'lib/tick_tock/clock.rb', line 60

def punch
  @punch
end

Class Method Details

.default ⇒ Clock

Returns an instance with the default configuration.

Returns:

  • (Clock) —

    an instance with the default configuration



62
63
64
65
 
# File 'lib/tick_tock/clock.rb', line 62

def self.default
  log_card = CardLogger.default.method(:call)
  with(punch: Punch.default, on_tick: log_card, on_tock: log_card)
end

.with(punch:, on_tick:, on_tock:) ⇒ Clock

Constructor accepting keyword args.

Parameters:

  • punch (Punch) —

    Implementation of Punch to use

  • on_tick (Proc, nil) —

    Callback on #tick

  • on_tock (Proc, nil) —

    Callback on #tock

Returns:



8
 
# File 'lib/tick_tock/clock.rb', line 8

def self.with(punch:, on_tick:, on_tock:); end

Instance Method Details

#tick(subject: nil) ⇒ Object

Starts timing a new card, calls any given #on_tick, and returns it.

Parameters:

  • subject (Object) (defaults to: nil) —

    Description of the subject we are timing

Returns:

  • (Object) —

    A new card representing the new timing context



71
72
73
74
75
76
77
 
# File 'lib/tick_tock/clock.rb', line 71

def tick(subject: nil)
  card = punch.card(subject: subject, parent_card: self.class.current_card)
  card_in = punch.in(card)
  self.class.current_card = card_in
  on_tick&.call(card_in)
  card_in
end

#tock(card:) ⇒ Object

Completes timing the given card, calls any given #on_tock, and returns it.

Parameters:

  • card (Object) —

    A card representing the timing context to complete

Returns:

  • (Object) —

    The card after being marked completed



84
85
86
87
88
89
 
# File 'lib/tick_tock/clock.rb', line 84

def tock(card:)
  card_out = punch.out(card)
  self.class.current_card = punch.parent_card_of(card_out)
  on_tock&.call(card_out)
  card_out
end

#with(punch: nil, on_tick: nil, on_tock: nil) ⇒ Clock

Returns a copy of this instance with any given values replaced.

Parameters:

  • punch (Punch) (defaults to: nil) —

    Implementation of Punch to use

  • on_tick (Proc, nil) (defaults to: nil) —

    Callback on #tick

  • on_tock (Proc, nil) (defaults to: nil) —

    Callback on #tock

Returns:

  • (Clock) —

    a copy of this instance with any given values replaced.



21
 
# File 'lib/tick_tock/clock.rb', line 21

def with(punch: nil, on_tick: nil, on_tock: nil); end