Actors
- class pykka.Actor(*args, **kwargs)[source]
To create an actor:
subclass one of the
Actor
implementations:implement your methods, including
__init__()
, as usual,call
Actor.start()
on your actor class, passing the method any arguments for your constructor.
To stop an actor, call
Actor.stop()
orActorRef.stop()
.For example:
import pykka class MyActor(pykka.ThreadingActor): def __init__(self, my_arg=None): super().__init__() ... # 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()
- classmethod start(*args, **kwargs)[source]
Start an actor and register it in the
ActorRegistry
.Any arguments passed to
start()
will be passed on to the class constructor.Behind the scenes, the following is happening when you call
start()
:The actor is created:
actor_urn
is initialized with the assigned URN.actor_inbox
is initialized with a new actor inbox.actor_ref
is initialized with apykka.ActorRef
object for safely communicating with the actor.At this point, your
__init__()
code can run.
The actor is registered in
pykka.ActorRegistry
.The actor receive loop is started by the actor’s associated thread/greenlet.
- Returns
a
ActorRef
which can be used to access the actor in a safe manner
- actor_urn = None
The actor URN string is a universally unique identifier for the actor. It may be used for looking up a specific actor using
ActorRegistry.get_by_urn()
.
- actor_inbox = None
The actor’s inbox. Use
ActorRef.tell()
,ActorRef.ask()
, and friends to put messages in the inbox.
- actor_stopped = None
A
threading.Event
representing whether or not the actor should continue processing messages. Usestop()
to change it.
- stop()[source]
Stop the actor.
It’s equivalent to calling
ActorRef.stop()
withblock=False
.
- on_start()[source]
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.If an exception is raised by this method the stack trace will be logged, and the actor will stop.
- on_stop()[source]
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.If an exception is raised by this method the stack trace will be logged, and the actor will stop.
- on_failure(exception_type, exception_value, traceback)[source]
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()
.If an exception is raised by this method the stack trace will be logged, and the actor will stop.
- class pykka.ActorRef(actor)[source]
Reference to a running actor which may safely be passed around.
ActorRef
instances are returned byActor.start()
and the lookup methods inActorRegistry
. You should never need to createActorRef
instances yourself.- Parameters
actor (
Actor
) – the actor to wrap
- actor_class = None
The class of the referenced actor.
- actor_urn = None
See
Actor.actor_urn
.
- actor_inbox = None
See
Actor.actor_inbox
.
- actor_stopped = None
See
Actor.actor_stopped
.
- is_alive()[source]
Check if actor is alive.
This is based on the actor’s stopped flag. The actor is not guaranteed to be alive and responding even though
is_alive()
returnsTrue
.- Returns
Returns
True
if actor is alive,False
otherwise.
- tell(message)[source]
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 (any) – message to send
- Raise
pykka.ActorDeadError
if actor is not available- Returns
nothing
- ask(message, block=True, timeout=None)[source]
Send message to actor and wait for the reply.
The message can be of any type. If
block
isFalse
, it will immediately return aFuture
instead of blocking.If
block
isTrue
, andtimeout
isNone
, as default, the method will block until it gets a reply, potentially forever. Iftimeout
is an integer or float, the method will wait for a reply fortimeout
seconds, and then raisepykka.Timeout
.- Parameters
message (any) – message to send
block (boolean) – whether to block while waiting for a reply
timeout (float or
None
) – seconds to wait before timeout if blocking
- Raise
pykka.Timeout
if timeout is reached if blocking- Raise
any exception returned by the receiving actor if blocking
- Returns
pykka.Future
, or response if blocking
- stop(block=True, timeout=None)[source]
Send a message to the actor, asking it to stop.
Returns
True
if actor is stopped or was being stopped at the time of the call.False
if actor was already dead. Ifblock
isFalse
, it returns a future wrapping the result.Messages sent to the actor before the actor is asked to stop will be processed normally before it stops.
Messages sent to the actor after the actor is asked to stop will be replied to with
pykka.ActorDeadError
after it stops.The actor may not be restarted.
block
andtimeout
works as forask()
.- Returns
pykka.Future
, or a boolean result if blocking
- proxy()[source]
Wraps the
ActorRef
in anActorProxy
.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