Rename start/return_thunk to on_start/return in CABI

lukewagner · lukewagner · commit 4d1030b56a92 · 2024-07-05T13:23:31.000-05:00
diff --git a/design/mvp/CanonicalABI.md b/design/mvp/CanonicalABI.md
@@ -681,16 +681,16 @@ async calls (until some active calls finish):
 ```python
 class AsyncTask(Task):
   ft: FuncType
-  start_thunk: Callable
-  return_thunk: Callable
+  on_start: Callable
+  on_return: Callable
   state: AsyncCallState
   unblock_next_pending: bool
 
-  def __init__(self, opts, inst, caller, ft, start_thunk, return_thunk):
+  def __init__(self, opts, inst, caller, ft, on_start, on_return):
     super().__init__(opts, inst, caller)
     self.ft = ft
-    self.start_thunk = start_thunk
-    self.return_thunk = return_thunk
+    self.on_start = on_start
+    self.on_return = on_return
     self.state = AsyncCallState.STARTING
     self.unblock_next_pending = False
 
@@ -1925,12 +1925,12 @@ When instantiating component instance `$inst`:
 The resulting function `$f` takes 3 runtime arguments:
 * `caller`: the caller's `Task` or, if this lifted function is being called by
   the host, `None`
-* `start_thunk`: a nullary function that must be called to return the caller's
+* `on_start`: a nullary function that must be called to return the caller's
   arguments as a list of component-level values
-* `return_thunk`: a unary function that must be called after `start_thunk`,
+* `on_return`: a unary function that must be called after `on_start`,
   passing the list of component-level return values
 
-The indirection of `start_thunk` and `return_thunk` are used to model the
+The indirection of `on_start` and `on_return` are used to model the
 interleaving of reading arguments out of the caller's stack and memory and
 writing results back into the caller's stack and memory, which will vary in
 async calls.
@@ -1949,21 +1949,21 @@ by a *single host-agnostic component*.
 
 Based on this, `canon_lift` is defined:
 ```python
-async def canon_lift(opts, inst, callee, ft, caller, start_thunk, return_thunk):
+async def canon_lift(opts, inst, callee, ft, caller, on_start, on_return):
   if opts.sync:
     task = SyncTask(opts, inst, caller)
     await task.enter()
 
-    flat_args = lower_sync_values(task, MAX_FLAT_PARAMS, start_thunk(), ft.param_types())
+    flat_args = lower_sync_values(task, MAX_FLAT_PARAMS, on_start(), ft.param_types())
     flat_results = await call_and_trap_on_throw(callee, task, flat_args)
-    return_thunk(lift_sync_values(task, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types()))
+    on_return(lift_sync_values(task, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types()))
 
     if opts.post_return is not None:
       [] = await call_and_trap_on_throw(opts.post_return, task, flat_results)
 
     task.exit()
   else:
-    task = AsyncTask(opts, inst, caller, ft, start_thunk, return_thunk)
+    task = AsyncTask(opts, inst, caller, ft, on_start, on_return)
     await task.enter()
 
     if not opts.callback:
@@ -1991,8 +1991,8 @@ async def call_and_trap_on_throw(callee, task, args):
 ```
 The only fundamental difference between sync and async lifting is whether
 parameters/results are automatically lowered/lifted (with `canon_lift` calling
-`start_thunk` and `return_thunk`) or whether the `callee` explicitly triggers
-`start_thunk`/`return_thunk` via `task.start`/`task.return` (defined below).
+`on_start` and `on_return`) or whether the `callee` explicitly triggers
+`on_start`/`on_return` via `task.start`/`task.return` (defined below).
 The latter gives the callee the ability to explicitly apply backpressure (by
 waiting before calling `task.start`) whereas the former applies "backpressure"
 immediately if a sync call is already running. In both cases, backpressure is
@@ -2050,29 +2050,29 @@ async def canon_lower(opts, callee, ft, task, flat_args):
   if opts.sync:
     subtask = Subtask(opts, task.inst)
 
-    def start_thunk():
+    def on_start():
       return lift_sync_values(subtask, MAX_FLAT_PARAMS, flat_args, ft.param_types())
 
-    def return_thunk(results):
+    def on_return(results):
       nonlocal flat_results
       flat_results = lower_sync_values(subtask, MAX_FLAT_RESULTS, results, ft.result_types(), flat_args)
 
-    await callee(task, start_thunk, return_thunk)
+    await callee(task, on_start, on_return)
 
     subtask.finish()
   else:
     subtask = AsyncSubtask(opts, task.inst)
 
     async def do_call():
-      def start_thunk():
+      def on_start():
         subtask.start()
         return lift_async_values(subtask, flat_args, ft.param_types())
 
-      def return_thunk(results):
+      def on_return(results):
         subtask.return_()
         lower_async_values(subtask, results, ft.result_types(), flat_args)
 
-      await callee(task, start_thunk, return_thunk)
+      await callee(task, on_start, on_return)
       subtask.finish()
 
     asyncio.get_event_loop().set_task_factory(asyncio.eager_task_factory)
@@ -2091,7 +2091,7 @@ async def canon_lower(opts, callee, ft, task, flat_args):
 In the async case, the combination of `asyncio.create_task` with
 `eager_task_factory` immediately start executing `do_call` without `await`ing
 it. Following `create_task`, `do_call` has either completed eagerly (with
-`return_thunk` having been called to write the return values into the
+`on_return` having been called to write the return values into the
 caller-supplied memory buffer), in which case the lowered function can simply
 return `0` to indicate "done". Otherwise, the coroutine is still running, in
 which case it is added to an instance-wide table of active async subtasks,
@@ -2246,7 +2246,7 @@ async def canon_task_start(task, core_ft, flat_args):
   trap_if(task.opts.sync)
   trap_if(core_ft != flatten_functype(CanonicalOptions(), FuncType([], task.ft.params), 'lower'))
   task.start()
-  args = task.start_thunk()
+  args = task.on_start()
   flat_results = lower_sync_values(task, MAX_FLAT_RESULTS, args, task.ft.param_types(), CoreValueIter(flat_args))
   assert(len(core_ft.results) == len(flat_results))
   return flat_results
@@ -2277,7 +2277,7 @@ async def canon_task_return(task, core_ft, flat_args):
   trap_if(core_ft != flatten_functype(CanonicalOptions(), FuncType(task.ft.results, []), 'lower'))
   task.return_()
   results = lift_sync_values(task, MAX_FLAT_PARAMS, CoreValueIter(flat_args), task.ft.result_types())
-  task.return_thunk(results)
+  task.on_return(results)
   assert(len(core_ft.results) == 0)
   return []
 ```
diff --git a/design/mvp/canonical-abi/definitions.py b/design/mvp/canonical-abi/definitions.py
@@ -506,16 +506,16 @@ def exit(self):
 
 class AsyncTask(Task):
   ft: FuncType
-  start_thunk: Callable
-  return_thunk: Callable
+  on_start: Callable
+  on_return: Callable
   state: AsyncCallState
   unblock_next_pending: bool
 
-  def __init__(self, opts, inst, caller, ft, start_thunk, return_thunk):
+  def __init__(self, opts, inst, caller, ft, on_start, on_return):
     super().__init__(opts, inst, caller)
     self.ft = ft
-    self.start_thunk = start_thunk
-    self.return_thunk = return_thunk
+    self.on_start = on_start
+    self.on_return = on_return
     self.state = AsyncCallState.STARTING
     self.unblock_next_pending = False
 
@@ -1357,21 +1357,21 @@ def lower_heap_values(cx, vs, ts, out_param):
 
 ### `canon lift`
 
-async def canon_lift(opts, inst, callee, ft, caller, start_thunk, return_thunk):
+async def canon_lift(opts, inst, callee, ft, caller, on_start, on_return):
   if opts.sync:
     task = SyncTask(opts, inst, caller)
     await task.enter()
 
-    flat_args = lower_sync_values(task, MAX_FLAT_PARAMS, start_thunk(), ft.param_types())
+    flat_args = lower_sync_values(task, MAX_FLAT_PARAMS, on_start(), ft.param_types())
     flat_results = await call_and_trap_on_throw(callee, task, flat_args)
-    return_thunk(lift_sync_values(task, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types()))
+    on_return(lift_sync_values(task, MAX_FLAT_RESULTS, CoreValueIter(flat_results), ft.result_types()))
 
     if opts.post_return is not None:
       [] = await call_and_trap_on_throw(opts.post_return, task, flat_results)
 
     task.exit()
   else:
-    task = AsyncTask(opts, inst, caller, ft, start_thunk, return_thunk)
+    task = AsyncTask(opts, inst, caller, ft, on_start, on_return)
     await task.enter()
 
     if not opts.callback:
@@ -1408,29 +1408,29 @@ async def canon_lower(opts, callee, ft, task, flat_args):
   if opts.sync:
     subtask = Subtask(opts, task.inst)
 
-    def start_thunk():
+    def on_start():
       return lift_sync_values(subtask, MAX_FLAT_PARAMS, flat_args, ft.param_types())
 
-    def return_thunk(results):
+    def on_return(results):
       nonlocal flat_results
       flat_results = lower_sync_values(subtask, MAX_FLAT_RESULTS, results, ft.result_types(), flat_args)
 
-    await callee(task, start_thunk, return_thunk)
+    await callee(task, on_start, on_return)
 
     subtask.finish()
   else:
     subtask = AsyncSubtask(opts, task.inst)
 
     async def do_call():
-      def start_thunk():
+      def on_start():
         subtask.start()
         return lift_async_values(subtask, flat_args, ft.param_types())
 
-      def return_thunk(results):
+      def on_return(results):
         subtask.return_()
         lower_async_values(subtask, results, ft.result_types(), flat_args)
 
-      await callee(task, start_thunk, return_thunk)
+      await callee(task, on_start, on_return)
       subtask.finish()
 
     asyncio.get_event_loop().set_task_factory(asyncio.eager_task_factory)
@@ -1491,7 +1491,7 @@ async def canon_task_start(task, core_ft, flat_args):
   trap_if(task.opts.sync)
   trap_if(core_ft != flatten_functype(CanonicalOptions(), FuncType([], task.ft.params), 'lower'))
   task.start()
-  args = task.start_thunk()
+  args = task.on_start()
   flat_results = lower_sync_values(task, MAX_FLAT_RESULTS, args, task.ft.param_types(), CoreValueIter(flat_args))
   assert(len(core_ft.results) == len(flat_results))
   return flat_results
@@ -1504,7 +1504,7 @@ async def canon_task_return(task, core_ft, flat_args):
   trap_if(core_ft != flatten_functype(CanonicalOptions(), FuncType(task.ft.results, []), 'lower'))
   task.return_()
   results = lift_sync_values(task, MAX_FLAT_PARAMS, CoreValueIter(flat_args), task.ft.result_types())
-  task.return_thunk(results)
+  task.on_return(results)
   assert(len(core_ft.results) == 0)
   return []
 
diff --git a/design/mvp/canonical-abi/run_tests.py b/design/mvp/canonical-abi/run_tests.py
@@ -391,12 +391,12 @@ async def dtor(task, args):
   rt2 = ResourceType(inst, dtor) # only usable in exports
   opts = mk_opts()
 
-  async def host_import(entered, start_thunk, return_thunk):
-    args = start_thunk()
+  async def host_import(entered, on_start, on_return):
+    args = on_start()
     assert(len(args) == 2)
     assert(args[0] == 42)
     assert(args[1] == 44)
-    return_thunk([45])
+    on_return([45])
 
   async def core_wasm(task, args):
     nonlocal dtor_value
@@ -460,15 +460,15 @@ async def core_wasm(task, args):
     Own(rt)
   ])
 
-  def arg_thunk():
+  def on_start():
     return [ 42, 43, 44, 13 ]
 
   got = None
-  def return_thunk(results):
+  def on_return(results):
     nonlocal got
     got = results
 
-  asyncio.run(canon_lift(opts, inst, core_wasm, ft, None, arg_thunk, return_thunk))
+  asyncio.run(canon_lift(opts, inst, core_wasm, ft, None, on_start, on_return))
 
   assert(len(got) == 3)
   assert(got[0] == 46)
@@ -498,13 +498,13 @@ async def core_eager_producer(task, args):
 
   fut1, fut2, fut3 = asyncio.Future(), asyncio.Future(), asyncio.Future()
   blocking_ft = FuncType([U8(),U8()], [U8()])
-  async def blocking_callee(entered, start_thunk, return_thunk):
+  async def blocking_callee(entered, on_start, on_return):
     await fut1
-    [x,y] = start_thunk()
+    [x,y] = on_start()
     assert(x == 83)
     assert(y == 84)
     await fut2
-    return_thunk([44])
+    on_return([44])
     await fut3
 
   consumer_heap = Heap(10)
@@ -577,16 +577,16 @@ async def dtor(task, args):
 
   ft = FuncType([Bool()],[U8()])
 
-  def arg_thunk():
+  def on_start():
     return [ True ]
 
   got = None
-  def return_thunk(results):
+  def on_return(results):
     nonlocal got
     got = results
 
   consumer_inst = ComponentInstance()
-  await canon_lift(consumer_opts, consumer_inst, consumer, ft, None, arg_thunk, return_thunk)
+  await canon_lift(consumer_opts, consumer_inst, consumer, ft, None, on_start, on_return)
   assert(len(got) == 1)
   assert(got[0] == 42)
 
@@ -596,10 +596,10 @@ async def test_async_callback():
   producer_inst = ComponentInstance()
 
   producer_ft = FuncType([], [])
-  async def producer(fut, entered, start_thunk, return_thunk):
-    start_thunk()
+  async def producer(fut, entered, on_start, on_return):
+    on_start()
     await fut
-    return_thunk([])
+    on_return([])
 
   fut1 = asyncio.Future()
   producer1 = partial(producer, fut1)
@@ -639,18 +639,18 @@ async def callback(task, args):
       return [0]
 
   consumer_inst = ComponentInstance()
-  def arg_thunk(): return []
+  def on_start(): return []
 
   got = None
-  def return_thunk(results):
+  def on_return(results):
     nonlocal got
     got = results
 
   opts = mk_opts()
   opts.sync = False
   opts.callback = callback
 
-  await canon_lift(opts, consumer_inst, consumer, consumer_ft, None, arg_thunk, return_thunk)
+  await canon_lift(opts, consumer_inst, consumer, consumer_ft, None, on_start, on_return)
   assert(got[0] == 83)
 
 asyncio.run(test_async_callback())
@@ -717,14 +717,14 @@ async def consumer(task, args):
     return []
 
   consumer_inst = ComponentInstance()
-  def arg_thunk(): return []
+  def on_start(): return []
 
   got = None
-  def return_thunk(results):
+  def on_return(results):
     nonlocal got
     got = results
 
-  await canon_lift(consumer_opts, consumer_inst, consumer, consumer_ft, None, arg_thunk, return_thunk)
+  await canon_lift(consumer_opts, consumer_inst, consumer, consumer_ft, None, on_start, on_return)
   assert(got[0] == 83)
 
 asyncio.run(test_async_to_sync())
@@ -733,10 +733,10 @@ async def test_sync_using_wait():
   inst = ComponentInstance()
   ft = FuncType([], [])
 
-  async def hostcall(fut, entered, start_thunk, return_thunk):
-    start_thunk()
+  async def hostcall(fut, entered, on_start, on_return):
+    on_start()
     await fut
-    return_thunk([])
+    on_return([])
   fut1 = asyncio.Future()
   hostcall1 = partial(hostcall, fut1)
   fut2 = asyncio.Future()
@@ -761,9 +761,9 @@ async def core_func(task, args):
     assert(callidx == 2)
     return []
 
-  def arg_thunk(): return []
-  def return_thunk(results): pass
-  await canon_lift(mk_opts(), inst, core_func, ft, None, arg_thunk, return_thunk)
+  def on_start(): return []
+  def on_return(results): pass
+  await canon_lift(mk_opts(), inst, core_func, ft, None, on_start, on_return)
 
 asyncio.run(test_sync_using_wait())
 
