pybricks.tools: Add helper for awaitable constants.

We have a few functions with this structure:

async def some_func():

    if simple_case:
        # This commits adds a helper to do this:
        return some_constant

    return await some_awaitable_operation()

Also apply this to the touch sensor value of the Powered Up device.

Author: laurensvalk

pybricks/tools/pb_type_async.c

@@ -103,7 +103,7 @@ MP_DEFINE_CONST_OBJ_TYPE(pb_type_async,
  * Returns an awaitable operation if the runloop is active, or awaits the
  * operation here and now.
  *
- * @param  [in]       config     Configuration of the operation
+ * @param  [in]       config     Configuration of the operation. NB: State will not be reset.
  * @param  [in, out]  prev       Candidate iterable object that might be re-used, otherwise assigned newly allocated object.
  * @param  [in]       stop_prev  Whether to stop ongoing awaitable if it is active.
  * @returns An awaitable if the runloop is active, otherwise the mapped return value.
@@ -147,3 +147,57 @@ mp_obj_t pb_type_async_wait_or_await(pb_type_async_t *config, pb_type_async_t **
     pb_assert(err);
     return config->return_map ? config->return_map(config->parent_obj) : mp_const_none;
 }
+
+/**
+ * Iteration for a constant awaitable that yields once before returning.
+ *
+ * This is different from omitting iter_once to achieve a single yield, since
+ * that special case cannot have a return value.
+ *
+ * @param  [in]   state        Protothread state.
+ * @param  [in]   parent_obj   The constant.
+ */
+static pbio_error_t pb_type_async_constant_iter_once(pbio_os_state_t *state, mp_obj_t parent_obj) {
+    PBIO_OS_ASYNC_BEGIN(state);
+    PBIO_OS_AWAIT_ONCE(state);
+    PBIO_OS_ASYNC_END(PBIO_SUCCESS);
+}
+
+/**
+ * Return map for a constant awaitable.
+ *
+ * @param  [in]   parent_obj   The constant.
+ * @returns                    The same constant.
+ */
+static mp_obj_t pb_type_async_constant_return_map(mp_obj_t parent_obj) {
+    return parent_obj;
+}
+
+/**
+ * Returns an awaitable operation that yields once and then returns a constant
+ * result. If the runloop is not active, this just returns the given value.
+ *
+ * Can be used to return constants from functions that still need to be
+ * awaitable for other reasons.
+ *
+ * @param  [in]       ret_obj    Return result.
+ * @param  [in, out]  prev       Candidate iterable object that might be
+ *                               re-used, otherwise assigned newly allocated object.
+ * @returns An awaitable if the runloop is active, otherwise the constant return value.
+ */
+mp_obj_t pb_type_async_return_constant(mp_obj_t ret_obj, pb_type_async_t **prev) {
+
+    // In synchronous mode, return right away.
+    if (!pb_module_tools_run_loop_is_active()) {
+        return ret_obj;
+    }
+
+    // Async case returns soon.
+    pb_type_async_t config = {
+        .parent_obj = ret_obj,
+        .iter_once = pb_type_async_constant_iter_once,
+        .return_map = pb_type_async_constant_return_map,
+        .state = 0,
+    };
+    return pb_type_async_wait_or_await(&config, prev, false);
+}

pybricks/tools/pb_type_async.h

@@ -75,6 +75,8 @@ typedef struct {
 
 mp_obj_t pb_type_async_wait_or_await(pb_type_async_t *config, pb_type_async_t **prev, bool stop_prev);
 
+mp_obj_t pb_type_async_return_constant(mp_obj_t ret_obj, pb_type_async_t **prev);
+
 void pb_type_async_schedule_stop_iteration(pb_type_async_t *iter);
 
 #endif // PYBRICKS_INCLUDED_ASYNC_H