simpy.events
— Core event types¶
This module contains the basic event types used in SimPy.
The base class for all events is Event
. Though it can be directly
used, there are several specialized subclasses of it.
Event (env) |
An event that may happen at some point in time. |
Timeout (env, delay[, value]) |
A Event that gets triggered after a delay has passed. |
Process (env, generator) |
Process an event yielding generator. |
AnyOf (env, events) |
A Condition event that is triggered if any of a list of events has been successfully triggered. |
AllOf (env, events) |
A Condition event that is triggered if all of a list of events have been successfully triggered. |
This module also defines the Interrupt
exception.
-
simpy.events.
PENDING
= object()¶ Unique object to identify pending values of events.
-
simpy.events.
URGENT
= 0¶ Priority of interrupts and process initialization events.
-
simpy.events.
NORMAL
= 1¶ Default priority used by events.
-
class
simpy.events.
Event
(env)¶ An event that may happen at some point in time.
An event
- may happen (
triggered
isFalse
), - is going to happen (
triggered
isTrue
) or - has happened (
processed
isTrue
).
Every event is bound to an environment env and is initially not triggered. Events are scheduled for processing by the environment after they are triggered by either
succeed()
,fail()
ortrigger()
. These methods also set the ok flag and the value of the event.An event has a list of
callbacks
. A callback can be any callable. Once an event gets processed, all callbacks will be invoked with the event as the single argument. Callbacks can check if the event was successful by examining ok and do further processing with the value it has produced.Failed events are never silently ignored and will raise an exception upon being processed. If a callback handles an exception, it must set
defused
toTrue
to prevent this.This class also implements
__and__()
(&
) and__or__()
(|
). If you concatenate two events using one of these operators, aCondition
event is generated that lets you wait for both or one of them.-
env
= None¶ The
Environment
the event lives in.
-
callbacks
= None¶ List of functions that are called when the event is processed.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
- may happen (
-
class
simpy.events.
Timeout
(env, delay, value=None)¶ A
Event
that gets triggered after a delay has passed.This event is automatically triggered when it is created.
-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
-
class
simpy.events.
Initialize
(env, process)¶ Initializes a process. Only used internally by
Process
.This event is automatically triggered when it is created.
-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
-
class
simpy.events.
Interruption
(process, cause)¶ Immediately schedules an
Interrupt
exception with the given cause to be thrown into process.This event is automatically triggered when it is created.
-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
-
class
simpy.events.
Process
(env, generator)¶ Process an event yielding generator.
A generator (also known as a coroutine) can suspend its execution by yielding an event.
Process
will take care of resuming the generator with the value of that event once it has happened. The exception of failed events is thrown into the generator.Process
itself is an event, too. It is triggered, once the generator returns or raises an exception. The value of the process is the return value of the generator or the exception, respectively.Note
Python version prior to 3.3 do not support return statements in generators. You can use :meth:~simpy.core.Environment.exit() as a workaround.
Processes can be interrupted during their execution by
interrupt()
.-
target
¶ The event that the process is currently waiting for.
Returns
None
if the process is dead or it is currently being interrupted.
-
is_alive
¶ True
until the process generator exits.
-
interrupt
(cause=None)¶ Interupt this process optionally providing a cause.
A process cannot be interrupted if it already terminated. A process can also not interrupt itself. Raise a
RuntimeError
in these cases.
-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
-
class
simpy.events.
Condition
(env, evaluate, events)¶ An event that gets triggered once the condition function evaluate returns
True
on the given list of events.The value of the condition event is an instance of
ConditionValue
which allows convenient access to the input events and their values. TheConditionValue
will only contain entries for those events that occurred before the condition is processed.If one of the events fails, the condition also fails and forwards the exception of the failing event.
The evaluate function receives the list of target events and the number of processed events in this list:
evaluate(events, processed_count)
. If it returnsTrue
, the condition is triggered. TheCondition.all_events()
andCondition.any_events()
functions are used to implement and (&
) and or (|
) for events.Condition events can be nested.
-
static
all_events
(events, count)¶ An evaluation function that returns
True
if all events have been triggered.
-
static
any_events
(events, count)¶ An evaluation function that returns
True
if at least one of events has been triggered.
-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
static
-
class
simpy.events.
AllOf
(env, events)¶ A
Condition
event that is triggered if all of a list of events have been successfully triggered. Fails immediately if any of events failed.-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
-
class
simpy.events.
AnyOf
(env, events)¶ A
Condition
event that is triggered if any of a list of events has been successfully triggered. Fails immediately if any of events failed.-
defused
¶ Becomes
True
when the failed event’s exception is “defused”.When an event fails (i.e. with
fail()
), the failed event’s value is an exception that will be re-raised when theEnvironment
processes the event (i.e. instep()
).It is also possible for the failed event’s exception to be defused by setting
defused
toTrue
from an event callback. Doing so prevents the event’s exception from being re-raised when the event is processed by theEnvironment
.
-
fail
(exception)¶ Set exception as the events value, mark it as failed and schedule it for processing by the environment. Returns the event instance.
Raises
ValueError
if exception is not anException
.Raises
RuntimeError
if this event has already been triggered.
-
ok
¶ Becomes
True
when the event has been triggered successfully.A “successful” event is one triggered with
succeed()
.Raises: AttributeError – if accessed before the event is triggered.
-
processed
¶ Becomes
True
if the event has been processed (e.g., its callbacks have been invoked).
-
succeed
(value=None)¶ Set the event’s value, mark it as successful and schedule it for processing by the environment. Returns the event instance.
Raises
RuntimeError
if this event has already been triggerd.
-
trigger
(event)¶ Trigger the event with the state and value of the provided event. Return self (this event instance).
This method can be used directly as a callback function to trigger chain reactions.
-
triggered
¶ Becomes
True
if the event has been triggered and its callbacks are about to be invoked.
-
value
¶ The value of the event if it is available.
The value is available when the event has been triggered.
Raises
AttributeError
if the value is not yet available.
-
-
class
simpy.events.
ConditionValue
¶ Result of a
Condition
. It supports convenient dict-like access to the triggered events and their values. The events are ordered by their occurences in the condition.
-
class
simpy.events.
Interrupt
¶ Exception thrown into a process if it is interrupted (see
interrupt()
).cause
provides the reason for the interrupt, if any.If a process is interrupted concurrently, all interrupts will be thrown into the process in the same order as they occurred.
-
cause
¶ The cause of the interrupt or
None
if no cause was provided.
-