Event basics

SimPy events are very similar – if not identical — to deferreds, futures or promises. Instances of the class Event are used to describe any kind of events. Events can be in one of the following states. An event

• might happen (not triggered),
• is going to happen (triggered) or
• has happened (processed).

They traverse these states exactly once in that order. Events are also tightly bound to time and time causes events to advance their state.

Initially, events are not triggered and just objects in memory.

If an event gets triggered, it is scheduled at a given time and inserted into SimPy’s event queue. The property Event.triggered becomes True.

As long as the event is not processed, you can add callbacks to an event. Callbacks are callables that accept an event as parameter and are stored in the Event.callbacks list.

An event becomes processed when SimPy pops it from the event queue and calls all of its callbacks. It is now no longer possible to add callbacks. The property Event.processed becomes True.

Events also have a value. The value can be set before or when the event is triggered and can be retrieved via Event.value or, within a process, by yielding the event (value = yield event).

>>> import simpy
>>>
>>> def my_callback(event):
...     print('Called back from', event)
...
>>> env = simpy.Environment()
>>> event = env.event()
>>> event.callbacks.append(my_callback)
>>> event.callbacks
[<function my_callback at 0x...>]

Example usages for Event

The simple mechanics outlined above provide a great flexibility in the way events (even the basic Event) can be used.

One example for this is that events can be shared. They can be created by a process or outside of the context of a process. They can be passed to other processes and chained:

>>> class School:
...     def __init__(self, env):
...         self.env = env
...         self.class_ends = env.event()
...         self.pupil_procs = [env.process(self.pupil()) for i in range(3)]
...         self.bell_proc = env.process(self.bell())
...
...     def bell(self):
...         for i in range(2):
...             yield self.env.timeout(45)
...             self.class_ends.succeed()
...             self.class_ends = self.env.event()
...             print()
...
...     def pupil(self):
...         for i in range(2):
...             print(' \o/', end='')
...             yield self.class_ends
...
>>> school = School(env)
>>> env.run()
 \o/ \o/ \o/
 \o/ \o/ \o/

This can also be used like the passivate / reactivate known from SimPy 2. The pupils passivate when class begins and are reactivated when the bell rings.

Let time pass by: the Timeout

To actually let time pass in a simulation, there is the timeout event. A timeout has two parameters: a delay and an optional value: Timeout(delay, value=None). It triggers itself during its creation and schedules itself at now + delay. Thus, the succeed() and fail() methods cannot be called again and you have to pass the event value to it when you create the timeout.

The delay can be any kind of number, usually an int or float as long as it supports comparison and addition.

Processes are events, too

SimPy processes (as created by Process or env.process()) have the nice property of being events, too.

That means, that a process can yield another process. It will then be resumed when the other process ends. The event’s value will be the return value of that process:

>>> def sub(env):
...     yield env.timeout(1)
...     return 23
...
>>> def parent(env):
...     ret = yield env.process(sub(env))
...     return ret
...
>>> env.run(env.process(parent(env)))
23

The example above will only work in Python >= 3.3. As a workaround for older Python versions, you can use env.exit(23) with the same effect.

When a process is created, it schedules an Initialize event which will start the execution of the process when triggered. You usually won’t have to deal with this type of event.

If you don’t want a process to start immediately but after a certain delay, you can use simpy.util.start_delayed(). This method returns a helper process that uses a timeout before actually starting a process.

The example from above, but with a delayed start of sub():

>>> from simpy.util import start_delayed
>>>
>>> def sub(env):
...     yield env.timeout(1)
...     return 23
...
>>> def parent(env):
...     start = env.now
...     sub_proc = yield start_delayed(env, sub(env), delay=3)
...     assert env.now - start == 3
...
...     ret = yield sub_proc
...     return ret
...
>>> env.run(env.process(parent(env)))
23

Waiting for for multiple events at once

Sometimes, you want to wait for more than one event at the same time. For example, you may want to wait for a resource, but not for an unlimited amount of time. Or you may want to wait until all of a number of events have happened.

SimPy therefore offers the AnyOf and AllOf events which both are a Condition event.

Both take a list of events as an argument and are triggered if at least one of them is triggered or all of them:

>>> from simpy.events import AnyOf, AllOf, Event
>>> events = [Event(env) for i in range(3)]
>>> a = AnyOf(env, events)  # Triggers if at least one of "events" is triggered.
>>> b = AllOf(env, events)  # Triggers if all each of "events" is triggered.

The value of a condition event is a dictionary with an entry for every triggered event. In the case of AllOf, the size of that dictionary will always be the same as the length of the event list. The value dict of AnyOf will have at least one entry. In both cases, the event instances are used as keys and the event values will be the values.

As a shorthand for AllOf and AnyOf, you can also use the logical operators & (and) and | (or):

>>> def test_condition(env):
...     t1, t2 = env.timeout(1, value='spam'), env.timeout(2, value='eggs')
...     ret = yield t1 | t2
...     assert ret == {t1: 'spam'}
...
...     t1, t2 = env.timeout(1, value='spam'), env.timeout(2, value='eggs')
...     ret = yield t1 & t2
...     assert ret == {t1: 'spam', t2: 'eggs'}
...
...     # You can also concatenate & and |
...     e1, e2, e3 = [env.timeout(i) for i in range(3)]
...     yield (e1 | e2) & e3
...     assert all(e.triggered for e in [e1, e2, e3])
...
>>> proc = env.process(test_condition(env))
>>> env.run()

That’s it. I’ve already started with the next guide – about process interaction – so hopefully it won’t take to long until publish it this time.