Actors API¶

High Level Functions¶

Actor¶

At the core of the library we have the Actor class which defines the primitive of pulsar concurrent framework. Actor’s instances communicate with each other via messages in a share-nothing architecture.

class pulsar.async.actor.Actor(impl)[source]¶

The base class for parallel execution in pulsar.

In computer science, the Actor model is a mathematical model of concurrent computation that treats actors as the universal primitives of computation. In response to a message that it receives, an actor can make local decisions, create more actors, send more messages, and determine how to respond to the next message received.

The current implementation allows for actors to perform specific tasks such as listening to a socket, acting as http server, consuming a task queue and so forth.

To spawn a new actor:

>>> from pulsar import spawn
>>> a = spawn()
>>> a.is_alive()
True

Here a is actually a reference to the remote actor, it is an ActorProxy.

ATTRIBUTES

name¶

The name of this Actor.

aid¶

Unique ID for this Actor.

impl¶

The Concurrency implementation for this Actor.

_loop¶

An event loop which listen for input/output events on sockets or socket-like objects. It is the driver of the Actor. If the _loop stops, the Actor stops running and goes out of scope.

mailbox¶

Used to send and receive actor messages.

address¶

The socket address for this Actor.mailbox.

proxy¶

Instance of a ActorProxy holding a reference to this Actor. The proxy is a lightweight representation of the actor which can be shared across different processes (i.e. it is picklable).

state¶

The actor numeric state.

extra¶

A dictionary which can be populated with extra parameters useful for other actors. This dictionary is included in the dictionary returned by the info() method. Check the info command for how to obtain information about an actor.

info_state¶

Current state description string. One of initial, running, stopping, closed and terminated.

next_periodic_task¶

The asyncio.Handle for the next actor periodic task.

stream¶

A stream handler to write information messages without using the logger.

monitors¶

Dictionary of monitors or None

managed_actors¶

Dictionary of managed actors or None

registered¶

Dictionary of registered actors or None

start(exit=True)[source]¶

Called after forking to start the actor’s life.

This is where logging is configured, the mailbox is registered and the _loop is initialised and started. Calling this method more than once does nothing.

send(target, action, *args, **kwargs)[source]¶

Send a message to target to perform action with given positional args and key-valued kwargs. Returns a coroutine or a Future.

spawn(**params)[source]¶

Spawn a new actor

stop(exc=None, exit_code=None)[source]¶

Gracefully stop the Actor.

Implemented by the Concurrency.stop() method of the impl attribute.

actorparams()[source]¶

Returns a dictionary of parameters for spawning actors.

The dictionary is passed to the spawn method when creating new actors. Fire the on_params actor hook.

is_running()[source]¶

True if actor is running, that is when the state is equal to ACTOR_STATES.RUN and the loop is running.

started()[source]¶

True if actor has started.

It does not necessarily mean it is running. Its state is greater or equal ACTOR_STATES.RUN.

after_run()[source]¶

True when the actor is sopping or has already stopped

closed()[source]¶

True if actor has exited in an clean fashion.

Its state is ACTOR_STATES.CLOSE.

stopped()[source]¶

True if actor has exited.

Its state is greater or equal to ACTOR_STATES.CLOSE.

is_arbiter()[source]¶

True if self is the arbiter

is_monitor()[source]¶

True if self is a monitor

is_process()[source]¶

boolean indicating if this is an actor on a child process.

get_actor(aid, check_monitor=True)[source]¶

Given an actor unique id return the actor proxy.

info()[source]¶

Return a nested dictionary of information related to the actor status and performance. The dictionary contains the following entries:

• actor a dictionary containing information regarding the type of actor and its status.
• events a dictionary of information about the event loop running the actor.
• extra the extra attribute (you can use it to add stuff).
• system system info.

This method is invoked when you run the info command from another actor.

Actor Internals¶

Messages¶

Actor communicate with each other via the send() function which uses the via Actor.mailbox attribute of the actor in the current context. When an actor communicate with another remote actor it does so by sending an action to it with positional and/or key-valued arguments. For example:

send(target, 'ping')

will send the ping action to target from the actor in the current context of execution. The above is equivalent to:

get_actor().send(target, 'ping')

Each action is implemented via the command() decorator implemented in the pulsar.async.commands module. A list of standard commands is available in the design documentation.

Concurrency¶

The Concurrency class implements the behaviour of an Actor and therefore allows for decoupling between the Actor abstraction and its implementation (bridge pattern).

Constants¶

Constants used throughout pulsar.

pulsar.async.consts.ACTOR_STATES = {'RUN': 3, 'TERMINATE': 6, 'DESCRIPTION': {0: 'initial', 1: 'inactive', 2: 'starting', 3: 'running', 4: 'stopping', 5: 'closed', 6: 'terminated'}, 'INITIAL': 0, 'CLOSE': 5, 'STOPPING': 4, 'INACTIVE': 1, 'STARTING': 2}¶

Actor state constants are access via:

from pulsar import ACTOR_STATES

They are:

• ACTOR_STATES.INITIAL = 0 when an actor is just created, before the pulsar.Actor.start method is called.
• ACTOR_STATES.STARTING = 2 when pulsar.Actor.start method is called.
• ACTOR_STATES.RUN = 3 when pulsar.Actor._loop is up and running.
• ACTOR_STATES.STOPPING = 4 when pulsar.Actor.stop has been called for the first time and the actor is running.

pulsar.async.consts.ACTOR_ACTION_TIMEOUT = 5¶

Important constant used by pulsar.Monitor to kill actors which don’t respond to the stop command.

pulsar.async.consts.MONITOR_TASK_PERIOD = 1¶

Interval for pulsar.Monitor and pulsar.Arbiter periodic task.