pybricks.tools: Include stop option when making object.

Almost everywhere we use pb_type_async_wait_or_await we stop the ongoing iteration first, so include that functionality as a bool.

It is still also available separately for methods that want to stop ongoing awaitables without spawning another one.

Also rename pb_type_async_schedule_cancel to pb_type_async_schedule_stop_iteration since cancel isn't quite the right word and this makes it more explicit what it does.

Author: laurensvalk

pybricks/common/pb_type_device.c

@@ -97,7 +97,7 @@ mp_obj_t pb_type_device_method_call(mp_obj_t self_in, size_t n_args, size_t n_kw
         .parent_obj = sensor_in,
         .return_map = method->get_values,
     };
-    return pb_type_async_wait_or_await(&config, &sensor->last_awaitable);
+    return pb_type_async_wait_or_await(&config, &sensor->last_awaitable, false);
 }
 
 /**
@@ -126,7 +126,7 @@ mp_obj_t pb_type_device_set_data(pb_type_device_obj_base_t *sensor, uint8_t mode
         .iter_once = pb_pup_device_iter_once,
         .parent_obj = MP_OBJ_FROM_PTR(sensor),
     };
-    return pb_type_async_wait_or_await(&config, &sensor->last_awaitable);
+    return pb_type_async_wait_or_await(&config, &sensor->last_awaitable, false);
 }
 
 void pb_device_set_lego_mode(pbio_port_t *port) {

pybricks/common/pb_type_lightmatrix.c

@@ -337,8 +337,7 @@ static mp_obj_t common_LightMatrix_text(size_t n_args, const mp_obj_t *pos_args,
         .iter_once = pb_type_lightmatrix_text_iterate_once,
     };
     // New operation always wins; ongoing animation is cancelled.
-    pb_type_async_schedule_cancel(self->text_iter);
-    return pb_type_async_wait_or_await(&config, &self->text_iter);
+    return pb_type_async_wait_or_await(&config, &self->text_iter, true);
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(common_LightMatrix_text_obj, 1, common_LightMatrix_text);
 

pybricks/common/pb_type_motor.c

@@ -243,7 +243,7 @@ static mp_obj_t pb_type_Motor_reset_angle(size_t n_args, const mp_obj_t *pos_arg
 
     // Set the new angle
     pb_assert(pbio_servo_reset_angle(self->srv, reset_angle, reset_to_abs));
-    pb_type_async_schedule_cancel(self->last_awaitable);
+    pb_type_async_schedule_stop_iteration(self->last_awaitable);
     return mp_const_none;
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_Motor_reset_angle_obj, 1, pb_type_Motor_reset_angle);
@@ -268,7 +268,7 @@ static mp_obj_t pb_type_Motor_run(size_t n_args, const mp_obj_t *pos_args, mp_ma
 
     mp_int_t speed = pb_obj_get_int(speed_in);
     pb_assert(pbio_servo_run_forever(self->srv, speed));
-    pb_type_async_schedule_cancel(self->last_awaitable);
+    pb_type_async_schedule_stop_iteration(self->last_awaitable);
     return mp_const_none;
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_Motor_run_obj, 1, pb_type_Motor_run);
@@ -277,7 +277,7 @@ static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_Motor_run_obj, 1, pb_type_Motor_run);
 static mp_obj_t pb_type_Motor_hold(mp_obj_t self_in) {
     pb_type_Motor_obj_t *self = MP_OBJ_TO_PTR(self_in);
     pb_assert(pbio_servo_stop(self->srv, PBIO_CONTROL_ON_COMPLETION_HOLD));
-    pb_type_async_schedule_cancel(self->last_awaitable);
+    pb_type_async_schedule_stop_iteration(self->last_awaitable);
     return mp_const_none;
 }
 static MP_DEFINE_CONST_FUN_OBJ_1(pb_type_Motor_hold_obj, pb_type_Motor_hold);
@@ -313,8 +313,7 @@ static mp_obj_t pb_type_motor_wait_or_await(pb_type_Motor_obj_t *self, bool retu
         .return_map = return_final_angle ? pb_type_motor_get_final_angle : NULL,
     };
     // New operation always wins; ongoing awaitable motor motion is cancelled.
-    pb_type_async_schedule_cancel(self->last_awaitable);
-    return pb_type_async_wait_or_await(&config, &self->last_awaitable);
+    return pb_type_async_wait_or_await(&config, &self->last_awaitable, true);
 }
 
 // pybricks.common.Motor.run_time
@@ -429,7 +428,7 @@ static mp_obj_t pb_type_Motor_track_target(size_t n_args, const mp_obj_t *pos_ar
 
     mp_int_t target_angle = pb_obj_get_int(target_angle_in);
     pb_assert(pbio_servo_track_target(self->srv, target_angle));
-    pb_type_async_schedule_cancel(self->last_awaitable);
+    pb_type_async_schedule_stop_iteration(self->last_awaitable);
     return mp_const_none;
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_Motor_track_target_obj, 1, pb_type_Motor_track_target);

pybricks/common/pb_type_speaker.c

@@ -113,8 +113,7 @@ static mp_obj_t pb_type_Speaker_beep(size_t n_args, const mp_obj_t *pos_args, mp
         .close = pb_type_Speaker_close,
     };
     // New operation always wins; ongoing sound awaitable is cancelled.
-    pb_type_async_schedule_cancel(self->iter);
-    return pb_type_async_wait_or_await(&config, &self->iter);
+    return pb_type_async_wait_or_await(&config, &self->iter, true);
 
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_Speaker_beep_obj, 1, pb_type_Speaker_beep);
@@ -325,8 +324,7 @@ static mp_obj_t pb_type_Speaker_play_notes(size_t n_args, const mp_obj_t *pos_ar
         .close = pb_type_Speaker_close,
     };
     // New operation always wins; ongoing sound awaitable is cancelled.
-    pb_type_async_schedule_cancel(self->iter);
-    return pb_type_async_wait_or_await(&config, &self->iter);
+    return pb_type_async_wait_or_await(&config, &self->iter, true);
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_Speaker_play_notes_obj, 1, pb_type_Speaker_play_notes);
 

pybricks/iodevices/pb_type_i2c_device.c

@@ -188,8 +188,7 @@ mp_obj_t pb_type_i2c_device_start_operation(mp_obj_t i2c_device_obj, const uint8
         .return_map = return_map ? pb_type_i2c_device_return_generic : NULL,
     };
     // New operation always wins; ongoing sound awaitable is cancelled.
-    pb_type_async_schedule_cancel(device->iter);
-    return pb_type_async_wait_or_await(&config, &device->iter);
+    return pb_type_async_wait_or_await(&config, &device->iter, true);
 }
 
 /**

pybricks/iodevices/pb_type_uart_device.c

@@ -103,8 +103,7 @@ static mp_obj_t pb_type_uart_device_write(size_t n_args, const mp_obj_t *pos_arg
         .parent_obj = MP_OBJ_FROM_PTR(self),
         .return_map = pb_type_uart_device_write_return_map,
     };
-    pb_type_async_schedule_cancel(self->write_iter);
-    return pb_type_async_wait_or_await(&config, &self->write_iter);
+    return pb_type_async_wait_or_await(&config, &self->write_iter, true);
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_uart_device_write_obj, 1, pb_type_uart_device_write);
 
@@ -146,8 +145,7 @@ static mp_obj_t pb_type_uart_device_read(size_t n_args, const mp_obj_t *pos_args
         .parent_obj = MP_OBJ_FROM_PTR(self),
         .return_map = pb_type_uart_device_read_return_map,
     };
-    pb_type_async_schedule_cancel(self->read_iter);
-    return pb_type_async_wait_or_await(&config, &self->read_iter);
+    return pb_type_async_wait_or_await(&config, &self->read_iter, true);
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_type_uart_device_read_obj, 1, pb_type_uart_device_read);
 

pybricks/robotics/pb_type_drivebase.c

@@ -100,7 +100,7 @@ static mp_obj_t pb_type_DriveBase_stop(mp_obj_t self_in) {
 
     // Cancel awaitables.
     pb_type_DriveBase_obj_t *self = MP_OBJ_TO_PTR(self_in);
-    pb_type_async_schedule_cancel(self->last_awaitable);
+    pb_type_async_schedule_stop_iteration(self->last_awaitable);
 
     // Stop hardware.
     pb_assert(pbio_drivebase_stop(self->db, PBIO_CONTROL_ON_COMPLETION_COAST));
@@ -119,8 +119,7 @@ static mp_obj_t await_or_wait(pb_type_DriveBase_obj_t *self) {
         .close = pb_type_DriveBase_stop,
     };
     // New operation always wins; ongoing awaitable motion is cancelled.
-    pb_type_async_schedule_cancel(self->last_awaitable);
-    return pb_type_async_wait_or_await(&config, &self->last_awaitable);
+    return pb_type_async_wait_or_await(&config, &self->last_awaitable, true);
 }
 
 // pybricks.robotics.DriveBase.straight
@@ -237,7 +236,7 @@ static mp_obj_t pb_type_DriveBase_drive(size_t n_args, const mp_obj_t *pos_args,
     mp_int_t turn_rate = pb_obj_get_int(turn_rate_in);
 
     // Cancel awaitables but not hardware. Drive forever will handle this.
-    pb_type_async_schedule_cancel(self->last_awaitable);
+    pb_type_async_schedule_stop_iteration(self->last_awaitable);
 
     pb_assert(pbio_drivebase_drive_forever(self->db, speed, turn_rate));
     return mp_const_none;
@@ -249,7 +248,7 @@ static mp_obj_t pb_type_DriveBase_brake(mp_obj_t self_in) {
 
     // Cancel awaitables.
     pb_type_DriveBase_obj_t *self = MP_OBJ_TO_PTR(self_in);
-    pb_type_async_schedule_cancel(self->last_awaitable);
+    pb_type_async_schedule_stop_iteration(self->last_awaitable);
 
     // Stop hardware.
     pb_assert(pbio_drivebase_stop(self->db, PBIO_CONTROL_ON_COMPLETION_BRAKE));

pybricks/tools/pb_module_tools.c

@@ -96,7 +96,7 @@ static mp_obj_t pb_module_tools_wait(size_t n_args, const mp_obj_t *pos_args, mp
         .state = pbdrv_clock_get_ms() + (uint32_t)time,
     };
 
-    return pb_type_async_wait_or_await(&config, &reuse);
+    return pb_type_async_wait_or_await(&config, &reuse, false);
 }
 static MP_DEFINE_CONST_FUN_OBJ_KW(pb_module_tools_wait_obj, 0, pb_module_tools_wait);
 
@@ -158,7 +158,7 @@ mp_obj_t pb_module_tools_pbio_task_wait_or_await(pbio_task_t *task) {
 
     // REVISIT: pbio tasks will be deprecated. Instead, protothreads can now
     // be safely awaited.
-    return pb_type_async_wait_or_await(&config, NULL);
+    return pb_type_async_wait_or_await(&config, NULL, false);
 }
 
 /**

pybricks/tools/pb_type_async.c

@@ -12,14 +12,19 @@
 #include <pybricks/util_pb/pb_error.h>
 
 /**
- * Cancels the iterable so it will stop awaiting.
+ * Makes the iterable exhaust the next time it is iterated.
  *
  * This will not call close(). Safe to call even if iter is NULL or if it is
  * already complete.
  *
+ * This is useful when all we need is for the ongoing awaitable to stop, with
+ * the newly created iterable taking care of the hardware. For example, if the
+ * new operation takes over the speaker, the old one only has to stop iterating,
+ * not stop the speaker as it would do with close().
+ *
  * @param [in] iter The awaitable object.
  */
-void pb_type_async_schedule_cancel(pb_type_async_t *iter) {
+void pb_type_async_schedule_stop_iteration(pb_type_async_t *iter) {
     if (!iter || iter->parent_obj == MP_OBJ_NULL) {
         // Don't schedule if already complete.
         return;
@@ -58,7 +63,7 @@ static mp_obj_t pb_type_async_iternext(mp_obj_t iter_in) {
 
     // Special case without iterator means yield exactly once and then complete.
     if (!iter->iter_once) {
-        pb_type_async_schedule_cancel(iter);
+        pb_type_async_schedule_stop_iteration(iter);
         return mp_const_none;
     }
 
@@ -98,22 +103,35 @@ 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]  prev       Candidate iterable object that might be re-used.
+ * @param  [in]       config     Configuration of the operation
+ * @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.
  */
-mp_obj_t pb_type_async_wait_or_await(pb_type_async_t *config, pb_type_async_t **prev) {
+mp_obj_t pb_type_async_wait_or_await(pb_type_async_t *config, pb_type_async_t **prev, bool stop_prev) {
 
     config->base.type = &pb_type_async;
 
     // Return allocated awaitable if runloop active.
     if (pb_module_tools_run_loop_is_active()) {
+
+        // Optionally schedule ongoing awaitable to stop (next time) if busy.
+        if (prev && stop_prev) {
+            pb_type_async_schedule_stop_iteration(*prev);
+        }
+
         // Re-use existing awaitable if exists and is free, otherwise allocate
         // another one. This allows many resources with one concurrent physical
         // operation like a motor to operate without re-allocation.
         pb_type_async_t *iter = (prev && *prev && (*prev)->parent_obj == MP_OBJ_NULL) ?
             *prev : (pb_type_async_t *)m_malloc(sizeof(pb_type_async_t));
+
+        // Copy the confuration to the object on heap so it lives on.
         *iter = *config;
+
+        // Attaches newly defined awaitable (or no-op if reused) to the parent
+        // object. The object that was here before is detached, so we no longer
+        // prevent it from being garbage collected.
         if (prev) {
             *prev = iter;
         }

pybricks/tools/pb_type_async.h

@@ -40,7 +40,7 @@ typedef mp_obj_t (*pb_type_async_return_map_t)(mp_obj_t parent_obj);
  */
 typedef pbio_error_t (*pb_type_async_iterate_once_t)(pbio_os_state_t *state, mp_obj_t parent_obj);
 
-// Object representing the iterable that is returned by an awaitable operation.
+/** Object representing the iterable that is returned by an awaitable operation. */
 typedef struct {
     mp_obj_base_t base;
     /**
@@ -49,8 +49,7 @@ typedef struct {
      *
      * Special values:
      *      MP_OBJ_NULL: This iterable has been fully exhausted and can be reused.
-     *      MP_OBJ_SENTINEL: This iterable is cancelled and will exhaust
-     *                             when it is iterated again.
+     *      MP_OBJ_SENTINEL: This iterable is will raise StopIteration when it is iterated again.
      */
     mp_obj_t parent_obj;
     /**
@@ -74,8 +73,8 @@ typedef struct {
     pbio_os_state_t state;
 } pb_type_async_t;
 
-mp_obj_t pb_type_async_wait_or_await(pb_type_async_t *config, pb_type_async_t **prev);
+mp_obj_t pb_type_async_wait_or_await(pb_type_async_t *config, pb_type_async_t **prev, bool stop_prev);
 
-void pb_type_async_schedule_cancel(pb_type_async_t *iter);
+void pb_type_async_schedule_stop_iteration(pb_type_async_t *iter);
 
 #endif // PYBRICKS_INCLUDED_ASYNC_H