Grouping Actors¶
Async¶
-
class
kingpin.actors.group.
Async
(*args, **kwargs)[source] Execute several
kingpin.actors.base.BaseActor
objects asynchronously.Groups together a series of Actors and executes them asynchronously - waiting until all of them finish before returning.
Options
Concurrency: Max number of concurrent executions. This will fire off N executions in parallel, and continue with the remained as soon as the first execution is done. This is faster than creating N Sync executions.
Acts: An array of individual Actor definitions.
Contexts: This variable can be one of two formats:
- A list of dictionaries with contextual tokens to pass into the actors
at instantiation time. If the list has more than one element, then
every actor defined in
acts
will be instantiated once for each item in thecontexts
list. - A dictionary of
file
andtokens
. The file should be a relative path with data formatted same as stated above. The tokens need to be the same format as a Macro actor: a dictionary passing token data to be used.
Timeouts
Timeouts are disabled specifically in this actor. The sub-actors can still raise their own
kingpin.actors.exceptions.ActorTimedOut
exceptions, but since the group actors run an arbitrary number of sub actors, we have chosen to not have this actor specifically raise its ownkingpin.actors.exceptions.ActorTimedOut
exception unless the user sets thetimeout
setting.Examples
Clone two arrays quickly.
{ "desc": "Clone two arrays", "actor": "group.Async", "options": { "contexts": [ { "ARRAY": "NewArray1" }, { "ARRAY": "NewArray2" } ], "acts": [ { "desc": "do something", "actor": "server_array.Clone", "options": { "source": "template", "dest": "{ARRAY}", } } ] } }
Dry Mode
Passes on the Dry mode setting to the sub-actors that are called.
Failure
In the event that one or more
acts
fail in this group, the entire group acts will return a failure to Kingpin. Because multiple actors are executing all at the same time, the all of these actors will be allowed to finish before the failure is returned.- A list of dictionaries with contextual tokens to pass into the actors
at instantiation time. If the list has more than one element, then
every actor defined in
Sync¶
-
class
kingpin.actors.group.
Sync
(*args, **kwargs)[source] Execute a series of
kingpin.actors.base.BaseActor
synchronously.Groups together a series of Actors and executes them synchronously in the order that they were defined.
Options
Acts: An array of individual Actor definitions.
Contexts: This variable can be one of two formats:
- A list of dictionaries with contextual tokens to pass into the actors
at instantiation time. If the list has more than one element, then
every actor defined in
acts
will be instantiated once for each item in thecontexts
list. - A string that points to a file with a list of contexts, just like the above dictionary.
- (_Deprecation warning, this is going away in v0.4.0. Use the ‘str’
method above!_) A dictionary of
file
andtokens
. The file should be a relative path with data formatted same as stated above. The tokens need to be the same format as a Macro actor: a dictionary passing token data to be used.
Timeouts
Timeouts are disabled specifically in this actor. The sub-actors can still raise their own
kingpin.actors.exceptions.ActorTimedOut
exceptions, but since the group actors run an arbitrary number of sub actors, we have chosen to not have this actor specifically raise its ownkingpin.actors.exceptions.ActorTimedOut
exception unless the user sets thetimeout
setting.Examples
Creates two arrays ... but sleeps 60 seconds between the two, then does not sleep at all after the last one:
{ "desc": "Clone, then sleep ... then clone, then sleep shorter...", "actor": "group.Sync", "options": { "contexts": [ { "ARRAY": "First", "SLEEP": "60", }, { "ARRAY": "Second", "SLEEP": "0", } ], "acts": [ { "desc": "do something", "actor": "server_array.Clone", "options": { "source": "template", "dest": "{ARRAY}" } }, { "desc": "sleep", "actor": "misc.Sleep", "options": { "sleep": "{SLEEP}", } } ] } }
Alternatively if no
contexts
are needed you can use thearray
syntax.[ { "actor": "server_array.Clone", "options": { "source": "template", "dest": "%ARRAY%" } }, { "actor": "misc.Sleep", "options": { "sleep": 30 } } ]
Dry Mode
Passes on the Dry mode setting to the acts that are called. Does not stop execution when one of the acts fails. Instead Group actor will finish all acts with warnings, and raise an error at the end of execution.
This provides the user with an insight to all the errors that are possible to encounter, rather than abort and quit on the first one.
Failure
In the event that an act fails, this actor will return the failure immediately. Because the acts are executed in-order of definition, the failure will prevent any further acts from executing.
The behavior is different in the dry run (read above.)
- A list of dictionaries with contextual tokens to pass into the actors
at instantiation time. If the list has more than one element, then
every actor defined in