Pykka’s version as a tuple that can be used for comparison
To create an actor:
To stop an actor, call Actor.stop() or ActorRef.stop().
For example:
from pykka.actor import ThreadingActor
class MyActor(ThreadingActor):
def __init__(self, my_arg=None):
... # My optional init code with access to start() arguments
def on_start(self):
... # My optional setup code in same context as on_receive()
def on_stop(self):
... # My optional cleanup code in same context as on_receive()
def on_failure(self, exception_type, exception_value, traceback):
... # My optional cleanup code in same context as on_receive()
def on_receive(self, message):
... # My optional message handling code for a plain actor
def a_method(self, ...):
... # My regular method to be used through an ActorProxy
my_actor_ref = MyActor.start(my_arg=...)
my_actor_ref.stop()
Start an actor and register it in the pykka.registry.ActorRegistry.
Any arguments passed to start() will be passed on to the class constructor.
Returns a ActorRef which can be used to access the actor in a safe manner.
Behind the scenes, the following is happening when you call start():
Actor.start()
Actor.__new__()
superclass.__new__()
superclass.__init__()
URN assignment
Inbox creation
ActorRef creation
Actor.__init__() # Your code can run here
ActorRegistry.register()
superclass.start()
The actor URN string is a universally unique identifier for the actor. It may be used for looking up a specific actor using pykka.registry.ActorRegistry.get_by_urn().
The actor’s inbox. Use ActorRef.send_one_way() and friends to put messages in the inbox.
Stop the actor.
The actor will finish processing any messages already in its queue before stopping. It may not be restarted.
Hook for doing any setup that should be done after the actor is started, but before it starts processing messages.
For ThreadingActor, this method is executed in the actor’s own thread, while __init__() is executed in the thread that created the actor.
Hook for doing any cleanup that should be done after the actor has processed the last message, and before the actor stops.
This hook is not called when the actor stops because of an unhandled exception. In that case, the on_failure() hook is called instead.
For ThreadingActor this method is executed in the actor’s own thread, immediately before the thread exits.
Hook for doing any cleanup after an unhandled exception is raised, and before the actor stops.
For ThreadingActor this method is executed in the actor’s own thread, immediately before the thread exits.
The method’s arguments are the relevant information from sys.exc_info().
May be implemented for the actor to handle regular non-proxy messages.
Messages where the value of the “command” key matches “pykka_*” are reserved for internal use in Pykka.
| Parameters: | message (picklable dict) – the message to handle |
|---|---|
| Returns: | anything that should be sent as a reply to the sender |
ThreadingActor implements Actor using regular Python threads.
This implementation is slower than pykka.gevent.GeventActor, but can be used in a process with other threads that are not Pykka actors.
Reference to a running actor which may safely be passed around.
ActorRef instances are returned by Actor.start() and the lookup methods in pykka.registry.ActorRegistry. You should never need to create ActorRef instances yourself.
| Parameters: | actor (Actor) – the actor to wrap |
|---|
See Actor.actor_urn
Check if actor is alive.
This is based on whether the actor is registered in the actor registry or not. The actor is not guaranteed to be alive and responding even though is_alive() returns True.
| Returns: | Returns True if actor is alive, False otherwise. |
|---|
Send message to actor without waiting for any response.
Will generally not block, but if the underlying queue is full it will block until a free slot is available.
| Parameters: | message (picklable dict) – message to send |
|---|---|
| Raise : | pykka.ActorDeadError if actor is not available |
| Returns: | nothing |
Send message to actor and wait for the reply.
The message must be a picklable dict. If block is False, it will immediately return a pykka.future.Future instead of blocking.
If block is True, and timeout is None, as default, the method will block until it gets a reply, potentially forever. If timeout is an integer or float, the method will wait for a reply for timeout seconds, and then raise pykka.Timeout.
| Parameters: |
|
|---|---|
| Raise : |
pykka.Timeout if timeout is reached |
| Raise : |
pykka.ActorDeadError if actor is not available |
| Returns: |
pykka.future.Future or response |
Send a message to the actor, asking it to stop.
The actor will finish processing any messages already in its queue before stopping. It may not be restarted.
block and timeout works as for send_request_reply().
| Returns: | True if actor is stopped. False if actor was already dead. |
|---|
Wraps the ActorRef in an pykka.proxy.ActorProxy.
Using this method like this:
proxy = AnActor.start().proxy()
is analogous to:
proxy = ActorProxy(AnActor.start())
| Raise : | pykka.ActorDeadError if actor is not available |
|---|---|
| Returns: | pykka.proxy.ActorProxy |
A Future is a handle to a value which are available or will be available in the future.
Typically returned by calls to actor methods or accesses to actor fields.
To get hold of the encapsulated value, call Future.get().
Get the value encapsulated by the future.
If the encapsulated value is an exception, it is raised instead of returned.
If timeout is None, as default, the method will block until it gets a reply, potentially forever. If timeout is an integer or float, the method will wait for a reply for timeout seconds, and then raise pykka.Timeout.
The encapsulated value can be retrieved multiple times. The future will only block the first time the value is accessed.
| Parameters: | timeout (float or None) – seconds to wait before timeout |
|---|---|
| Raise : | pykka.Timeout if timeout is reached |
| Raise : | encapsulated value if it is an exception |
| Returns: | encapsulated value if it is not an exception |
ThreadingFuture implements Future for use with pykka.actor.ThreadingActor.
The future is implemented using a Queue.Queue.
The encapsulated value is a copy made with copy.deepcopy(), unless the encapsulated value is another ThreadingFuture, in which case the original future is encapsulated.
Collect all values encapsulated in the list of futures.
If timeout is not None, the method will wait for a reply for timeout seconds, and then raise pykka.Timeout.
| Parameters: |
|
|---|---|
| Raise : |
pykka.Timeout if timeout is reached |
| Returns: |
list of results |
An ActorProxy wraps an pykka.actor.ActorRef. The proxy allows the referenced actor to be used through a normal method calls and field access.
You can create an ActorProxy from any pykka.actor.ActorRef:
actor_ref = MyActor.start()
actor_proxy = ActorProxy(actor_ref)
You can also get an ActorProxy by using pykka.actor.ActorRef.proxy():
actor_proxy = MyActor.start().proxy()
When reading an attribute or getting a return value from a method, you get a pykka.future.Future object back. To get the enclosed value from the future, you must call pykka.future.Future.get() on the returned future:
print actor_proxy.string_attribute.get()
print actor_proxy.count().get() + 1
If you call a method just for it’s side effects and do not care about the return value, you do not need to accept the returned future or call pykka.future.Future.get() on the future. Simply call the method, and it will be executed concurrently with your own code:
actor_proxy.method_with_side_effect()
If you want to block your own code from continuing while the other method is processing, you can use pykka.future.Future.get() to block until it completes:
actor_proxy.method_with_side_effect().get()
An example of ActorProxy usage:
#! /usr/bin/env python
from pykka.actor import ThreadingActor
from pykka.registry import ActorRegistry
class Adder(ThreadingActor):
def add_one(self, i):
print '%s is increasing %d' % (self, i)
return i + 1
class Bookkeeper(ThreadingActor):
def __init__(self, adder):
self.adder = adder
def count_to(self, target):
i = 0
while i < target:
i = self.adder.add_one(i).get()
print '%s got %d back' % (self, i)
if __name__ == '__main__':
adder = Adder.start().proxy()
bookkeeper = Bookkeeper.start(adder).proxy()
bookkeeper.count_to(10).get()
ActorRegistry.stop_all()
| Parameters: | actor_ref (pykka.actor.ActorRef) – reference to the actor to proxy |
|---|---|
| Raise : | pykka.ActorDeadError if actor is not available |
The actor’s pykka.actor.ActorRef instance.
Registry which provides easy access to all running actors.
Contains global state, but should be thread-safe.
Broadcast message to all actors of the specified target_class.
If no target_class is specified, the message is broadcasted to all actors.
| Parameters: |
|
|---|
Get pykka.actor.ActorRef for all running actors.
| Returns: | list of pykka.actor.ActorRef |
|---|
Get ActorRef for all running actors of the given class, or of any subclass of the given class.
| Parameters: | actor_class (class) – actor class, or any superclass of the actor |
|---|---|
| Returns: | list of pykka.actor.ActorRef |
Get ActorRef for all running actors of the given class name.
| Parameters: | actor_class_name (string) – actor class name |
|---|---|
| Returns: | list of pykka.actor.ActorRef |
Get an actor by its universally unique URN.
| Parameters: | actor_urn (string) – actor URN |
|---|---|
| Returns: | pykka.actor.ActorRef or None if not found |
Register an ActorRef in the registry.
This is done automatically when an actor is started, e.g. by calling pykka.actor.Actor.start().
| Parameters: | actor_ref (pykka.actor.ActorRef) – reference to the actor to register |
|---|
Stop all running actors.
block and timeout works as for pykka.actor.ActorRef.stop().
If block is True, the actors are guaranteed to be stopped in the reverse of the order they were started in. This is helpful if you have simple dependencies in between your actors, where it is sufficient to shut down actors in a LIFO manner: last started, first stopped.
If you have more complex dependencies in between your actors, you should take care to shut them down in the required order yourself, e.g. by stopping dependees from a dependency’s pykka.actor.Actor.on_stop() method.
| Returns: | If not blocking, a list with a future for each stop action. If blocking, a list of return values from pykka.actor.ActorRef.stop(). |
|---|
Remove an pykka.actor.ActorRef from the registry.
This is done automatically when an actor is stopped, e.g. by calling pykka.actor.Actor.stop().
| Parameters: | actor_ref (pykka.actor.ActorRef) – reference to the actor to unregister |
|---|