Events

UPSTAGE Events mimic the SimPy events, and provide features that enable interrupts, rehearsal and other features with Task Networks.

All events accept a rehearsal_time_to_complete argument.

The available UPSTAGE events are:

Event

Mimics SimPy’s raw Event, useful for marking pauses until a success.

See create_knowledge_event() for a use case.

One use case is the knowledge event, which enables a way to publish and event to an actor, and have some other source succeed it.

class ActorTask(UP.Task):
    def task(self, *, actor):
        event = actor.create_knowledge_event(name="pause")
        yield event


class ManagerTask(UP.Task):
    def task(self, *, actor):
        subordinate: UP.Actor = actor.subordinates[0]
        subordinate.succeed_knowledge_event(name="pause", some_data={...})

Wait

A standard SimPy timeout. Can be explicit or generate from a random uniform distribution.

The random uniform distribution accepts an input for the rehearsal time, while the base version rehearses at the given time.

yield UP.Wait(3.14)
...
yield UP.Wait.from_random_uniform(low, high, rehearsal_time_to_complete=high)

Get

Get from a store or container.

get_event = UP.Get(some_store)
item = yield get_event
assert item == get_event.get_value()

amount = 12.3
get_event = UP.Get(some_container, amount)
yield get_event
assert get_event.get_value() == amount

FilterGet

A get with a filter function, used for SimPy’s FilterStore.

get_event = UP.FilterGet(some_store, filter=lambda item: item.value > 10)
item = yield get_event

SortedFilterGet

A get with a filter or sorting function, used with SortedFilterStore, and others.

get_event = UP.SortedFilterGet(
    some_store,
    filter=lambda item: item.value > 10,
    sorter=lambda item: (item.property, item.other_property),
)
item = yield get_event

Put

Put something into a store or container

item = [1,2,3.4]
put_event = UP.Put(some_store, item)
yield put_event
assert item in some_store.items

amount = 12.3
yield UP.Put(some_store, amount)

ResourceHold

Put and release holds on limited resources.

a_resource = SIM.Resource(env, capacity=1)
request_object = UP.ResourceHold(a_resource)
yield request_object
# Now you have a hold on the resource
...
yield request_object
# Now you've given it back

All

Succeed when all passed events succeed.

get_event = UP.Get(some_store)
wait_event = UP.Wait(3.14)
yield Any(get_event, wait_event)

assert get_event.is_complete()
assert wait_event.is_complete()

Any

Succeed when any passed events succeed

get_event = UP.Get(some_store)
wait_event = UP.Wait(3.14)
yield Any(get_event, wait_event)

# Determine what passed
if get_event.is_complete():
    item = get_event.get_value()
else:
    # cancel the get or else it will succeed
    get_event.cancel()