Module: Eventbox::Timer

Extended by:
Boxable
Defined in:
lib/eventbox/timer.rb

Overview

Simple timer services for Eventboxes

This module can be included into Eventbox classes to add simple timer functions.

class MyBox < Eventbox
  include Eventbox::Timer

  async_call def init
    super   # make sure Timer#init is called
    timer_after(1) do
      puts "one second elapsed"
    end
  end
end

The main functions are timer_after and timer_every. They schedule asynchronous calls to the given block:

timer_after(3) do
  # executed once after 3 seconds
end

timer_every(3) do
  # executed repeatedly every 3 seconds
end

Both functions return an Alarm object which can be used to cancel the alarm through timer_cancel.

timer_after, timer_every and timer_cancel can be used within the event scope, in actions and from external scope.

Timer always uses one action thread per Eventbox object, regardless of the number of scheduled timers.

Defined Under Namespace

Classes: Alarm, InternalError, OneTimeAlarm, Reload, RepeatedAlarm

Class Method Summary collapse

Class Method Details

.action(name, &block) ⇒ Object (private) Originally defined in module Boxable

Define a private method for asynchronous execution.

The call to the action method returns immediately after starting a new action. It returns an Action object. By default each call to an action method spawns a new thread which executes the code of the action definition. Alternatively a threadpool can be assigned by Eventbox.with_options.

All method arguments are passed through the Sanitizer.

Actions can return state changes or objects to the event loop by calls to methods created by #async_call, #sync_call or #yield_call or through calling Eventbox#async_proc, Eventbox#sync_proc or Eventbox#yield_proc objects. To avoid unsafe shared objects, an action has it’s own set of local variables or instance variables. It doesn’t have access to variables defined by other methods.

The Action object can be used to interrupt the program execution by an exception. See Action for further information. If the action method accepts one more argument than given to the action call, it is set to corresponding Action instance:

async_call def init
  do_something("value1")
end
action def do_something(str, action)
  str              # => "value1"
  action.current?  # => true
  # `action' can be passed to event scope or external scope,
  # in order to send a signals per Action#raise
end

.async_call(name, &block) ⇒ Object (private) Originally defined in module Boxable

Define a threadsafe method for asynchronous (fire-and-forget) calls.

The created method can be safely called from any thread. All method arguments are passed through the Sanitizer. Arguments prefixed by a € sign are automatically passed as WrappedObject.

The method itself might not do any blocking calls or expensive computations - this would impair responsiveness of the Eventbox instance. Instead use #action in these cases.

In contrast to #sync_call it’s not possible to call external blocks or proc objects from #async_call methods.

The method always returns self to the caller.

.attr_accessor(name) ⇒ Object (private) Originally defined in module Boxable

Threadsafe read and write access to instance variables.

Attention: Be careful with read-modify-write operations - they are not atomic but are executed as two independent operations.

This will lose counter increments, since ‘counter` is incremented in a non-atomic manner:

attr_accessor :counter
async_call def start
  10.times { do_something }
end
action def do_something
  self.counter += 1
end

Instead don’t use accessors but do increments within one method call like so:

async_call def start
  10.times { do_something }
end
action def do_something
  increment 1
end
async_call def increment(by)
  @counter += by
end

.attr_reader(name) ⇒ Object (private) Originally defined in module Boxable

Threadsafe read access to instance variables.

.attr_writer(name) ⇒ Object (private) Originally defined in module Boxable

Threadsafe write access to instance variables.

.sync_call(name, &block) ⇒ Object (private) Originally defined in module Boxable

Define a method for synchronous calls.

The created method can be safely called from any thread. It is simular to #async_call, but the method waits until the method body is executed and returns its return value. Since all processing within the event scope of an Eventbox instance must not involve blocking operations, sync calls can only return immediate values. For deferred results use #yield_call instead.

It’s possible to call external blocks or proc objects from #sync_call methods. Blocks are executed by the same thread that calls the #sync_call method to that time.

All method arguments as well as the result value are passed through the Sanitizer. Arguments prefixed by a € sign are automatically passed as WrappedObject.

The method itself might not do any blocking calls or expensive computations - this would impair responsiveness of the Eventbox instance. Instead use #action in these cases.

.yield_call(name, &block) ⇒ Object (private) Originally defined in module Boxable

Define a method for calls with deferred result.

This call type is simular to #sync_call, however it’s not the result of the method that is returned. Instead the method is called with one additional argument in the event scope, which is used to yield a result value or raise an exception. In contrast to a return statement, the execution of the method continues after yielding a result.

The result value can be yielded within the called method, but it can also be stored and called by any other event scope or external method, leading to a deferred method return. The external thread calling this method is suspended until a result is yielded. However the Eventbox object keeps responsive to calls from other threads.

The created method can be safely called from any thread. If yield methods are called in the event scope, they must get a Proc object as the last argument. It is called when a result was yielded.

It’s possible to call external blocks or proc objects from #yield_call methods up to the point when the result was yielded. Blocks are executed by the same thread that calls the #yield_call method to that time.

All method arguments as well as the result value are passed through the Sanitizer. Arguments prefixed by a € sign are automatically passed as WrappedObject.

The method itself as well as the Proc object might not do any blocking calls or expensive computations - this would impair responsiveness of the Eventbox instance. Instead use #action in these cases.