Two settings let a task leave without being served:
Reneging: a task's patience is how long it may wait before it leaves the queue and publishes reneged.
Balking: a task's balk is a condition checked before it joins the queue. When the condition holds, the task publishes balked and never requests the resource.
Patience covers the task's wait, then its resource and then its get. It counts waiting time only and pauses while the task is served, so a task that is preempted and queues again goes on with the time it has left. A get that gives up is cancelled, so it takes nothing later.
Here each order brings its own patience as an attribute, which its arrival sets with attributes:, and no order joins after the courier's last collection at 100 seconds:
arrivals:orders:dist:exponentialrate:0.5spawn:packattributes:{patience:20}walk_ins:dist:exponentialrate:0.1spawn:packattributes:{patience:10}tasks:pack:service:packingresource:packers# Each order's own patience: it leaves the queue when it runs out.patience:attr.patience# No new orders once the courier has made its last collection.balk:t >= 100payload:{event_type:order_packed}
@app.task(service_id="packing",resource_id="packers",# Each order's own patience: it leaves the queue when it runs outpatience="attr.patience",# No new orders once the courier has made its last collectionbalk="t >= 100",)defpack(task_id,context):"""Packs one order."""return{"event_type":"order_packed"}
defpack(env,sampler,packers,key,patience,task_id):"""Balks after 100 s; otherwise waits at most `patience` for a packer."""path_id="Shop.service.packing"defpublish(value):env.publish_event(key,value,task="pack",instance=task_id)flow=key.rsplit("-",1)[0]env.stats.flow_started(flow)# the order enters the shop# No new orders once the courier has made its last collectionifenv.now>=100:publish({"path_id":path_id,"sim_id":"Shop","service":"packing","status":"balked",})env.stats.task_balked("pack",task_id)env.stats.flow_ended(flow)returnpublish({"path_id":path_id,"sim_id":"Shop","service":"packing","status":"queued"})env.stats.task_queued("pack",task_id)withpackers.request()asreq:# Each order's own patience: it leaves the queue when it runs outresult=yieldreq|env.timeout(patience)ifreqnotinresult:publish({"path_id":path_id,"sim_id":"Shop","service":"packing","status":"reneged",})env.stats.task_reneged("pack",task_id)env.stats.flow_ended(flow)returnpublish({"path_id":path_id,"sim_id":"Shop","service":"packing","status":"started",})env.stats.task_started("pack",task_id)yieldenv.timeout(sampler.sample(env.registry.get_config(path_id)))publish({"event_type":"order_packed"})env.stats.task_finished("pack",task_id)env.stats.flow_finished(flow)
A low-level process writes both by hand: an if before the request, and SimPy's result = yield request | env.timeout(patience), which resumes when either event is processed. request not in result tells that the patience came first. Leaving the with block takes a waiting request out of the queue at once, so it is never granted later.
patience takes seconds, a duration such as 30 s, an expression such as attr.patience, or in the builder a function of the task id and the entity's attributes. balk takes any condition an expression can write, such as level.stock == 0.
Go On After Leaving
An order that reneges or balks publishes reneged or balked, and its flow ends there. on_renege and on_balk name a task for it to go on to instead. on_renege needs patience, and on_balk needs balk, resource, seize or open. The task they name reads the status of the task the order left as upstream.status, which is reneged or balked, and the Builder takes both as arguments of task.
One packer packs for 3 seconds and an order arrives every second, with a patience of 4 seconds. No order joins from 8 seconds on. Both ways of leaving go to the same task, follow_up, which records how the order left:
pack:service:packingresource:packerspatience:4balk:t >= 8# Where an order goes after it leaves the line, by reneging or by balkingon_renege:follow_upon_balk:follow_uppayload:{event_type:order_packed}follow_up:payload:event_type:order_left# reneged or balked: the status of the task the order came fromhow:{gen:expr, expr:upstream.status}
@app.task(name="pack",service_id="packing",resource_id="packers",patience=4,balk="t >= 8",# Where an order goes after it leaves the line, by reneging or by balkingon_renege="follow_up",on_balk="follow_up",)defpack(task_id):"""Packs one order."""return{"event_type":"order_packed"}# reneged or balked: the status of the task the order came fromfollow_up_payload=Template({"event_type":"order_left","how":{"gen":"expr","expr":"upstream.status"}},name="tasks.follow_up",)@app.task(name="follow_up")deffollow_up(task_id):"""Records how the order left the line."""returnfollow_up_payload
deffollow_up(key,how):"""Records how the order left the line."""value={"event_type":"order_left","how":how}env.publish_event(key,value,task="follow_up",instance=sent["follow_up"])sent["follow_up"]+=1defpack(number):key=f"orders-{number}"ifenv.now>=8:# balk: t >= 8follow_up(key,"balked")returnwithpackers.request()asunit:# SimPy's request | timeout: the patience is 4 secondsresult=yieldunit|env.timeout(4)ifunitnotinresult:follow_up(key,"reneged")returnyieldenv.timeout(sampler.sample(env.registry.get_config("Shop.service.packing")))env.publish_event(key,{"event_type":"order_packed"},task="pack",instance=number-1)
A low-level process has no on_renege. It calls the follow-up itself where it leaves the line, and follow_up publishes the record.
Of the 12 orders, 4 are packed (1, 2, 4 and 7), 3 renege (3, 5 and 6) and 5 balk (8 to 12). Each of the 8 that leave publishes an order_left record from follow_up with its how.
Run the YAML file from the root of a clone of the repository and keep the records of follow_up:
The Builder and Low-level scripts, reneging_follow_up.py and reneging_follow_up_low_level.py, publish the same records, which a test checks.
Settle a Tie Between a Grant and a Patience
A unit can come free at the same instant a waiting order's patience runs out. Plain SimPy settles this with no rule of its own: the wait ends with whichever event is processed first, and the order is served only when its request is in the result. The unit is granted by an event that the holder's release schedules at the instant of the release. The patience's timeout was scheduled when the order began to wait, so it comes first. desflow grants units with the same events SimPy uses, so it gives the same answer:
an order that arrived at 3 with a patience of 3, while the holder started at 0 with 6 seconds of service, reneges at 6;
an order that arrived at 0 with a patience of 6, just after the holder, reneges at 6 as well;
an order that arrived at 3 with a patience of 4 is served, because the unit is granted at 6 and the patience ends at 7.
Each form runs both from one script, check_reneging.py, made of the blocks in this section and the next, in order. It starts with the imports of the standard library and a class that keeps every record the model publishes. The imports of desflow follow the class, in the line from desflow import CapacityConfig, DynamicRealtimeEnvironment, DynamicResource, Sampler, SimParameter, SimulationContext:
importasyncioimportimportlib.utilimportqueueimportshutilimporttempfilefromcollectionsimportCounterfrompathlibimportPathclassCapture:"""An egress that keeps every record it receives."""def__init__(self):self.records=[]asyncdefrun(self,egress_queue):try:whileTrue:try:self.records.extend(egress_queue.get_nowait())exceptqueue.Empty:awaitasyncio.sleep(0.005)exceptasyncio.CancelledError:pass
The function _outcome tells what the order did, from the records of its pack task:
def_outcome(records:list)->str:"""What the order did: reneged if any record of its pack task says so."""statuses=[r["value"].get("status")forrinrecordsifr["stream_type"]=="event"andr["task"]=="pack"]return"reneged"if"reneged"instatuseselse"served"
The YAML form replays the two arrivals at their times from CSV files. Save its blueprint as reneging_tie.yaml beside the script:
simulation:{sim_id:Shop, factor:0}resources:packers:{current_cap:1, max_cap:1}services:hold:{dist:constant, value:6}packing:{dist:constant, value:1}arrivals:holders:replay:{path:holders.csv}spawn:holderorders:replay:{path:orders.csv}spawn:packtasks:holder:service:holdresource:packerspayload:{event_type:held}pack:service:packingresource:packerspatience:attr.patience# from the patience column of orders.csvpayload:{event_type:order_packed}run:{until:8}
tie_yaml replays the holder at 0 and the order from CSV files beside the blueprint:
deftie_yaml(waiter_at:float,patience:float,blueprint:str="reneging_tie.yaml",)->str:"""The same, with the blueprint and the two arrivals replayed from CSV files."""withtempfile.TemporaryDirectory()astmp:folder=Path(tmp)shutil.copy(blueprint,folder/"reneging_tie.yaml")(folder/"holders.csv").write_text("time\n0\n")(folder/"orders.csv").write_text(f"time,patience\n{waiter_at},{patience}\n")app=SimulationContext.from_yaml(folder/"reneging_tie.yaml")capture=Capture()app.add_egress(capture)app.run()# until 8, from the blueprintreturn_outcome(capture.records)
deftie(waiter_at:float,patience:float)->str:"""The outcome of an order whose patience may end when the packer comes free."""app=SimulationContext("Shop",factor=0)app.add_resource("packers",current_cap=1,max_cap=1)app.add_service("hold",dist="constant",value=6)app.add_service("packing",dist="constant",value=1)capture=Capture()app.add_egress(capture)@app.task(service_id="hold",resource_id="packers")defholder(task_id):return{"event_type":"held"}@app.task(service_id="packing",resource_id="packers",patience=patience)defpack(task_id):return{"event_type":"order_packed"}defscript(context):context.spawn(holder(0))# takes the packer at 0 and keeps it until 6ifwaiter_at:yieldcontext.env.timeout(waiter_at)context.spawn(pack(0))yieldcontext.env.timeout(0)app.add_process(script)app.run(until=8)return_outcome(capture.records)
deftie_low_level(waiter_at:float,patience:float)->str:"""The same, with SimPy's request | timeout."""env=DynamicRealtimeEnvironment(factor=0)env.registry.register_sim_parameter(SimParameter(sim_id="Shop",resources={"packers":CapacityConfig(current_cap=1,max_cap=1)},))capture=Capture()env.setup_egress([capture])packers=DynamicResource(env,"Shop","packers")defholder():withpackers.request()asunit:yieldunityieldenv.timeout(6)# keeps the packer until 6defpack():ifwaiter_at:# at 0, its patience starts before the holder's serviceyieldenv.timeout(waiter_at)withpackers.request()asunit:result=yieldunit|env.timeout(patience)ifunitnotinresult:env.publish_event("orders-1",{"status":"reneged"},"pack",0)returnyieldenv.timeout(1)env.publish_event("orders-1",{"event_type":"order_packed"},"pack",0)env.process(holder())env.process(pack())env.run(until=8)env.teardown()return_outcome(capture.records)
In each form, an order arriving at 3 with a patience of 3, or at 0 with a patience of 6, reneges, and one arriving at 3 with a patience of 4 is served. A model that must not depend on this order can avoid exact ties, for example by drawing patience from a distribution.
Check the Result
Every order that arrives ends in one of four places: packed, reneged, balked, or still in the shop when the run ends, waiting (queued) or being packed (started). The last event of each entity key says which. With statistics at basic or above, the finished, reneged and balked counts must match those events. This function checks them, and is the same for every form:
defbalance(records:list,stats:dict)->Counter:"""Every order that arrived, by what became of it."""last={}forrecordinrecords:ifrecord["stream_type"]=="event":value=record["value"]last[record["key"]]=value.get("status",value.get("event_type"))outcome=Counter(last.values())# queued or started: still in the shop when the run endedname="Shop.stats.tasks.pack.{}".formatassertoutcome["order_packed"]==stats[name("finished")]assertoutcome["reneged"]==stats.get(name("reneged"),0)assertoutcome["balked"]==stats.get(name("balked"),0)returnoutcome
Each form runs the example below for 120 seconds with a capturing egress, and passes what it captured to balance. Run desflow examples get patience in the folder of the script first. The forms read the example from patience/yaml/, patience/builder/ and patience/low-level/, and a function loads an example file without running it:
def_example(path:str):"""Loads an example script as a module, without running it."""spec=importlib.util.spec_from_file_location("patience_example",path)assertspecisnotNoneandspec.loaderisnotNonemodule=importlib.util.module_from_spec(spec)spec.loader.exec_module(module)returnmodule
defyaml_form(path:str="patience/yaml/patience.yaml")->Counter:app=SimulationContext.from_yaml(path)capture=Capture()app.add_egress(capture)app.run()# until 120, from the blueprintreturnbalance(capture.records,app.env.stats.readings())
deflow_level_form(path:str="patience/low-level/patience_example.py")->Counter:example=_example(path)env=DynamicRealtimeEnvironment(factor=0)env.registry.register_sim_parameter(example.PARAMS)capture=Capture()env.setup_egress([capture])env.setup_stats("Shop","basic",interval=30.0)packers=example.build(env)forprocessinexample.processes(env,Sampler(seed=42),packers):env.process(process)env.run(until=120)env.teardown()# publishes the last statistics and flushes the capturereturnbalance(capture.records,env.stats.readings())
Last, the script prints the results of the ties and of the three forms. The example also prints its events, so keep the lines that start with check::
if__name__=="__main__":print("check: arrives at 3, patience 3:",tie(3,3))print("check: arrives at 0, patience 6:",tie(0,6))print("check: arrives at 3, patience 4:",tie(3,4))print("check: the same in YAML:",tie_yaml(3,3),tie_yaml(0,6),tie_yaml(3,4))print("check: the same, low-level:",tie_low_level(3,3),tie_low_level(0,6),tie_low_level(3,4),)forformin(yaml_form,builder_form,low_level_form):print("check:",dict(form()))
check: arrives at 3, patience 3: reneged
check: arrives at 0, patience 6: reneged
check: arrives at 3, patience 4: served
check: the same in YAML: reneged reneged served
check: the same, low-level: reneged reneged served
check: {'order_packed': 51, 'reneged': 13, 'balked': 5}
check: {'order_packed': 51, 'reneged': 13, 'balked': 5}
check: {'order_packed': 51, 'reneged': 13, 'balked': 5}
Each form returns 51 packed, 13 reneged and 5 balked, 69 orders in all, and no order is still in the shop. A mean wait counts only the orders that were served, so report the reneged and balked counts beside it.
Example
The patience example is the model above: one packer, online orders with a patience of 20 seconds and walk-in orders with 10, and no new orders from 100 seconds. It needs no Docker service and ends on its own after 120 simulation seconds.
Quick Start
desflow examples get downloads the example at the release you install, into a folder of its own. Pick uv or pip: