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/iodevices/pb_type_iodevices_pupdevice.c

@@ -165,18 +165,6 @@ static mp_obj_t get_pup_data_tuple(mp_obj_t self_in) {
     return mp_obj_new_tuple(mode_info[current_mode].num_values, values);
 }
 
-static mp_obj_t iodevices_PUPDevice_touch_sensor_true(mp_obj_t self_in) {
-    return mp_const_true;
-}
-
-static mp_obj_t iodevices_PUPDevice_touch_sensor_false(mp_obj_t self_in) {
-    return mp_const_false;
-}
-
-static pbio_error_t iodevices_PUPDevice_touch_sensor_iter_once(pbio_os_state_t *state, mp_obj_t self_in) {
-    return PBIO_SUCCESS;
-}
-
 // pybricks.iodevices.PUPDevice.read
 static mp_obj_t iodevices_PUPDevice_read(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     PB_PARSE_ARGS_METHOD(n_args, pos_args, kw_args,
@@ -189,19 +177,7 @@ static mp_obj_t iodevices_PUPDevice_read(size_t n_args, const mp_obj_t *pos_args
     if (self->passive_id == LEGO_DEVICE_TYPE_ID_LPF2_TOUCH) {
         uint32_t value;
         pb_assert(pbio_port_get_analog_value(self->port, self->passive_id, false, &value));
-
-        if (!pb_module_tools_run_loop_is_active()) {
-            return mp_obj_new_bool(value);
-        }
-
-        // REVISIT: we could probably make something more efficient here.
-        pb_type_async_t config = {
-            .parent_obj = MP_OBJ_FROM_PTR(self),
-            .iter_once = iodevices_PUPDevice_touch_sensor_iter_once,
-            .return_map = value ? iodevices_PUPDevice_touch_sensor_true : iodevices_PUPDevice_touch_sensor_false,
-        };
-
-        return pb_type_async_wait_or_await(&config, &self->device_base.last_awaitable, false);
+        return pb_type_async_return_result(mp_obj_new_bool(value), &self->device_base.last_awaitable);
     }
 
     // Other passive devices don't support reading.

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]       result_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_result(mp_obj_t result_obj, pb_type_async_t **prev) {
+
+    // In synchronous mode, return right away.
+    if (!pb_module_tools_run_loop_is_active()) {
+        return result_obj;
+    }
+
+    // Async case returns soon.
+    pb_type_async_t config = {
+        .parent_obj = result_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_result(mp_obj_t result_obj, pb_type_async_t **prev);
+
 void pb_type_async_schedule_stop_iteration(pb_type_async_t *iter);
 
 #endif // PYBRICKS_INCLUDED_ASYNC_H