module Celluloid - celluloid-0.16.0 Documentation

# module Celluloid

### Constants

BARE_OBJECT_WARNING_MESSAGE

  Warning message added to Celluloid objects accessed outside their actors

DeadActorError

  Trying to do something to a dead actor

Error

  Base class of all Celluloid errors

LINKING_TIMEOUT

  Linking times out after 5 seconds

NotActorError

  Don't do Actor-like things outside Actor scope

OWNER_IVAR
TIMER_QUANTUM

  Timer accuracy enforced by the tests (50ms)

TaskSet

  Assume we're on MRI, where we have the GIL. But what about IronRuby? Or MacRuby. Do people care? This will break Celluloid::StackDumps

TimeoutError

  A timeout occured before the given request could complete

VERSION

### Attributes

actor_system[W]
logger[RW]
shutdown_timeout[RW]
task_class[RW]

### Public Class Methods

actor?() click to toggle source

Are we currently inside of an actor?

    # File lib/celluloid.rb, line 66
    def actor?
      !!Thread.current[:celluloid_actor]
    end

actor_system() click to toggle source

    # File lib/celluloid.rb, line 24
    def actor_system
      if Thread.current.celluloid?
        Thread.current[:celluloid_actor_system] or raise Error, "actor system not running"
      else
        Thread.current[:celluloid_actor_system] || @actor_system or raise Error, "Celluloid is not yet started; use Celluloid.boot"
      end
    end

boot() click to toggle source

    # File lib/celluloid.rb, line 120
    def boot
      init
      start
    end

cores() click to toggle source

Obtain the number of CPUs in the system

    # File lib/celluloid.rb, line 81
    def cores
     CPUCounter.cores
    end

Also aliased as: cpus, ncpus
cpus()
Alias for: cores
detect_recursion() click to toggle source

Detect if a particular call is recursing through multiple actors

    # File lib/celluloid.rb, line 94
    def detect_recursion
      actor = Thread.current[:celluloid_actor]
      return unless actor

      task = Thread.current[:celluloid_task]
      return unless task

      chain_id = CallChain.current_id
      actor.tasks.to_a.any? { |t| t != task && t.chain_id == chain_id }
    end

dump(output = STDERR)
Alias for: stack_dump
exception_handler(&block) click to toggle source

Define an exception handler for actor crashes

    # File lib/celluloid.rb, line 106
    def exception_handler(&block)
      Logger.exception_handler(&block)
    end

included(klass) click to toggle source

    # File lib/celluloid.rb, line 32
    def included(klass)
      klass.send :extend,  ClassMethods
      klass.send :include, InstanceMethods

      klass.send :extend, Properties

      klass.property :mailbox_class, :default => Celluloid::Mailbox
      klass.property :proxy_class,   :default => Celluloid::CellProxy
      klass.property :task_class,    :default => Celluloid.task_class
      klass.property :mailbox_size

      klass.property :exclusive_actor, :default => false
      klass.property :exclusive_methods, :multi => true
      klass.property :execute_block_on_receiver,
        :default => [:after, :every, :receive],
        :multi   => true

      klass.property :finalizer
      klass.property :exit_handler_name

      klass.send(:define_singleton_method, :trap_exit) do |*args|
        exit_handler_name(*args)
      end

      klass.send(:define_singleton_method, :exclusive) do |*args|
        if args.any?
          exclusive_methods(*exclusive_methods, *args)
        else
          exclusive_actor true
        end
      end
    end

init() click to toggle source

    # File lib/celluloid.rb, line 125
    def init
      @actor_system = ActorSystem.new
    end

mailbox() click to toggle source

Retrieve the mailbox for the current thread or lazily initialize it

    # File lib/celluloid.rb, line 71
    def mailbox
      Thread.current[:celluloid_mailbox] ||= Celluloid::Mailbox.new
    end

ncpus()
Alias for: cores
register_shutdown() click to toggle source

    # File lib/celluloid.rb, line 137
    def register_shutdown
      return if @shutdown_registered
      # Terminate all actors at exit
      at_exit do
        if defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby" && RUBY_VERSION >= "1.9"
          # workaround for MRI bug losing exit status in at_exit block
          # http://bugs.ruby-lang.org/issues/5218
          exit_status = $!.status if $!.is_a?(SystemExit)
          Celluloid.shutdown
          exit exit_status if exit_status
        else
          Celluloid.shutdown
        end
      end
      @shutdown_registered = true
    end

running?() click to toggle source

    # File lib/celluloid.rb, line 133
    def running?
      actor_system && actor_system.running?
    end

shutdown() click to toggle source

Shut down all running actors

    # File lib/celluloid.rb, line 155
    def shutdown
      actor_system.shutdown
    end

stack_dump(output = STDERR) click to toggle source

Perform a stack dump of all actors to the given output object

    # File lib/celluloid.rb, line 88
    def stack_dump(output = STDERR)
      actor_system.stack_dump.print(output)
    end

Also aliased as: dump
start() click to toggle source

    # File lib/celluloid.rb, line 129
    def start
      actor_system.start
    end

suspend(status, waiter) click to toggle source

    # File lib/celluloid.rb, line 110
    def suspend(status, waiter)
      task = Thread.current[:celluloid_task]
      if task && !Celluloid.exclusive?
        waiter.before_suspend(task) if waiter.respond_to?(:before_suspend)
        Task.suspend(status)
      else
        waiter.wait
      end
    end

uuid() click to toggle source

Generate a Universally Unique Identifier

    # File lib/celluloid.rb, line 76
    def uuid
      UUID.generate
    end

version() click to toggle source

    # File lib/celluloid.rb, line 159
    def version
      VERSION
    end

### Public Instance Methods

abort(cause) click to toggle source

Raise an exception in sender context, but stay running

    # File lib/celluloid.rb, line 310
    def abort(cause)
      cause = case cause
        when String then RuntimeError.new(cause)
        when Exception then cause
        else raise TypeError, "Exception object/String expected, but #{cause.class} received"
      end
      raise AbortError.new(cause)
    end

after(interval, &block) click to toggle source

Call a block after a given interval, returning a Celluloid::Timer object

    # File lib/celluloid.rb, line 424
    def after(interval, &block)
      Thread.current[:celluloid_actor].after(interval, &block)
    end

async(meth = nil, *args, &block) click to toggle source

Handle async calls within an actor itself

    # File lib/celluloid.rb, line 443
    def async(meth = nil, *args, &block)
      Thread.current[:celluloid_actor].behavior_proxy.async meth, *args, &block
    end

call_chain_id() click to toggle source

Obtain the UUID of the current call chain

    # File lib/celluloid.rb, line 340
    def call_chain_id
      CallChain.current_id
    end

current_actor() click to toggle source

Obtain the #current_actor

    # File lib/celluloid.rb, line 335
    def current_actor
      Actor.current
    end

defer(&block) click to toggle source

Perform a blocking or computationally intensive action inside an asynchronous thread pool, allowing the sender to continue processing other messages in its mailbox in the meantime

    # File lib/celluloid.rb, line 436
    def defer(&block)
      # This implementation relies on the present implementation of
      # Celluloid::Future, which uses a thread from InternalPool to run the block
      Future.new(&block).value
    end

every(interval, &block) click to toggle source

Call a block every given interval, returning a Celluloid::Timer object

    # File lib/celluloid.rb, line 429
    def every(interval, &block)
      Thread.current[:celluloid_actor].every(interval, &block)
    end

exclusive(&block) click to toggle source

Run given block in an exclusive mode: all synchronous calls block the whole actor, not only current message processing.

    # File lib/celluloid.rb, line 413
    def exclusive(&block)
      Thread.current[:celluloid_task].exclusive(&block)
    end

exclusive?() click to toggle source

Are we currently exclusive

    # File lib/celluloid.rb, line 418
    def exclusive?
      task = Thread.current[:celluloid_task]
      task && task.exclusive?
    end

future(meth = nil, *args, &block) click to toggle source

Handle calls to future within an actor itself

    # File lib/celluloid.rb, line 448
    def future(meth = nil, *args, &block)
      Thread.current[:celluloid_actor].behavior_proxy.future meth, *args, &block
    end

link(actor) click to toggle source

Link this actor to another, allowing it to crash or react to errors

    # File lib/celluloid.rb, line 365
    def link(actor)
      Actor.link(actor)
    end

linked_to?(actor) click to toggle source

Is this actor linked to another?

    # File lib/celluloid.rb, line 380
    def linked_to?(actor)
      Actor.linked_to?(actor)
    end

links() click to toggle source

Obtain the Celluloid::Links for this actor

    # File lib/celluloid.rb, line 350
    def links
      Thread.current[:celluloid_actor].links
    end

monitor(actor) click to toggle source

Watch for exit events from another actor

    # File lib/celluloid.rb, line 355
    def monitor(actor)
      Actor.monitor(actor)
    end

monitoring?(actor) click to toggle source

Are we monitoring another actor?

    # File lib/celluloid.rb, line 375
    def monitoring?(actor)
      Actor.monitoring?(actor)
    end

receive(timeout = nil, &block) click to toggle source

Receive an asynchronous message via the actor protocol

    # File lib/celluloid.rb, line 385
    def receive(timeout = nil, &block)
      actor = Thread.current[:celluloid_actor]
      if actor
        actor.receive(timeout, &block)
      else
        Celluloid.mailbox.receive(timeout, &block)
      end
    end

signal(name, value = nil) click to toggle source

Send a signal with the given name to all waiting methods

    # File lib/celluloid.rb, line 325
    def signal(name, value = nil)
      Thread.current[:celluloid_actor].signal name, value
    end

sleep(interval) click to toggle source

Sleep letting the actor continue processing messages

    # File lib/celluloid.rb, line 395
    def sleep(interval)
      actor = Thread.current[:celluloid_actor]
      if actor
        actor.sleep(interval)
      else
        Kernel.sleep interval
      end
    end

tasks() click to toggle source

Obtain the running tasks for this actor

    # File lib/celluloid.rb, line 345
    def tasks
      Thread.current[:celluloid_actor].tasks.to_a
    end

terminate() click to toggle source

Terminate this actor

    # File lib/celluloid.rb, line 320
    def terminate
      Thread.current[:celluloid_actor].behavior_proxy.terminate!
    end

timeout(duration) { || ... } click to toggle source

Timeout on task suspension (eg Sync calls to other actors)

    # File lib/celluloid.rb, line 405
    def timeout(duration)
      Thread.current[:celluloid_actor].timeout(duration) do
        yield
      end
    end

unlink(actor) click to toggle source

Remove links to another actor

    # File lib/celluloid.rb, line 370
    def unlink(actor)
      Actor.unlink(actor)
    end

unmonitor(actor) click to toggle source

Stop waiting for exit events from another actor

    # File lib/celluloid.rb, line 360
    def unmonitor(actor)
      Actor.unmonitor(actor)
    end

wait(name) click to toggle source

Wait for the given signal

    # File lib/celluloid.rb, line 330
    def wait(name)
      Thread.current[:celluloid_actor].wait name
    end