Documentation for pulsar 0.7.2. For development docs, go here.
This method can be used from any Actor. If not in the Arbiter domain, the method sends a request to the Arbiter to spawn a new actor. Once the arbiter creates the actor it returns the proxy to the original caller.
These optional parameters are:
A typical usage:
>>> def do_something(actor): ... >>> a = spawn(start=do_something, ...) >>> a.aid 'ba42b02b' >>> a.called True >>> p = a.result >>> p.address ('127.0.0.1', 46691)
Send a message to target
The message is to perform a given action. The actor sending the message is obtained via the get_actor() function.
a Deferred if the action acknowledge the caller or None.
>>> a = spawn() >>> r = a.add_callback(lambda p: send(p,'ping')) >>> r.result 'pong'
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.
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.
An instance of EventLoop which listen for input/output events on sockets or socket-like Transport. It is the driver of the Actor. If the :attr:event_loop` stps, the Actor stop running and goes out of scope.
A pulsar.utils.structures.AttributeDictionary which contains parameters which are passed to actors spawned by this actor.
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.
Current state description string. One of initial, running, stopping, closed and terminated.
A stream handler to write information messages without using the logger.
Called after forking to start the actor’s life.
Send a message to target to perform action with given positional args and key-valued kwargs. Always return a Deferred.
Gracefully stop the Actor.
|Parameters:||workers – number of threads to use in the ThreadPool. If not supplied, the value in the thread_workers setting is used.|
True if actor has started. It does not necessarily mean it is running. Its state is greater or equal ACTOR_STATES.RUN.
boolean indicating if this is an actor on a child process.
Given an actor unique id return the actor proxy.
Return a nested dictionary of information related to the actor status and performance. The dictionary contains the following entries:
This method is invoked when you run the info command from another actor.
A monitor is a very special Actor.
The Arbiter manages monitors which in turn manage a set of Actor performing similar tasks.
In other words, you may have a monitor managing actors for serving HTTP requests on a given port, another monitor managing actors consuming tasks from a task queue and so forth. You can think of Monitor as managers of pools of Actor.
Monitors are created by invoking the Arbiter.add_monitor() functions and not by directly invoking the constructor. Therefore adding a new monitor to the arbiter follows the pattern:
import pulsar m = pulsar.arbiter().add_monitor('mymonitor')
Monitor specific task called by the Monitor.periodic_task().
By default it does nothing. Override if you need to.
The Arbiter drives pulsar servers.
It is the most important a Actor and PoolMixin in pulsar concurrent framework. It is used as singleton in the main process and it manages one or more Monitor. It runs the main EventLoop of your concurrent application. It is the equivalent of the gunicorn arbiter, the twisted reactor and the tornado eventloop.
Users access the arbiter (in the arbiter process domain) by the high level api:
import pulsar arbiter = pulsar.arbiter()
the pulsar.Monitor added.
Given an actor unique id return the actor proxy.
Not an actor per se, this is a mixin for Actor which manages a pool (group) of actors. Given an actor_class it makes sure there are always cfg.workers alive. It is used by both the Arbiter and the Monitor classes.
dictionary with keys given by actor’s ids and values by ActorProxyMonitor instances. These are the actors managed by the pool.
list of ActorProxyMonitor which have been terminated (the remote actor did not have a cleaned shutdown).
The class derived form Actor which the monitor manages during its life time.
alias of Actor
Returns a dictionary of parameters for spawning actors.
The disctionary is passed to the spawn method when creating new actors. Fire the on_params actor hook.
|Parameters:||stop – if True stops all alive actor.|
If an actor failed to notify itself to the arbiter for more than the timeout, stop the actor.
if the actor is alive 0 if it is not.
Maintain the number of workers by spawning or killing as required.
A proxy for a remote Actor.
This is a lightweight class which delegates function calls to the underlying remote object.
It is picklable and therefore can be send from actor to actor using actor message passing.
For example, lets say we have a proxy a, to send a message to it:
from pulsar import send send(a, 'echo', 'hello there!')
will send the command echo to actor a with parameter "hello there!".
A specialised ActorProxy class.
This is the connection with the remote actor. It is available once the actor handshake between the actor and the monitor has completed. The mailbox is a server-side pulsar.async.mailbox.MailboxConsumer instance and it is used by the send() function to send messages to the remote actor.
True if underlying actor is alive.
Terminate life of underlying actor.
Wait until the underlying actor terminates.
If timeout is provided, it raises an exception if the timeout is reached.
Start the remote actor.
A thread pool for an actor.
This pool maintains a group of threads to perform asynchronous tasks via the apply() method.
String status of this pool.
Number of threads in the pool.
Equivalent to func(*args, **kwargs).
This method create a new task for function func and adds it to the queue. Return a Deferred called back once the task has finished.
Shut down the event loop of threads
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:
will send the ping action to target from the actor in the current context of execution. The above is equivalent to:
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.
Decorator for pulsar command functions.
|Parameters:||ack – True if the command acknowledge the sender with a response. Usually is set to True (which is also the default value).|
Responsible for the actual spawning of actors according to a concurrency implementation. Instances are picklable and are shared between the Actor and its ActorProxyMonitor. This is an abstract class, derived classes must implement the start method.
Return a IO poller instance which sets the EventLoop.io handler. By default it return nothing so that the best handler for the system is chosen.
Start running the actor.
Set up the event loop for actor.
Must be implemented by subclasses.
Create the mailbox for actor.
Implement the actor period task.
Gracefully stop the actor.
Daemonise the system if required.
Override Concurrency.create_mailbox() to create the mailbox server.
Constants used throughout pulsar.
Actor state constants are access via:
from pulsar import ACTOR_STATES
Important constant used by pulsar.Monitor to kill actors which don’t respond to the stop command.