many renamings; add overflowed flag to EventQuque

Author: dhalbert

shared-bindings/keypad/Event.c

@@ -32,44 +32,44 @@
 
 //| class Event:
 //|     """A key transition event."""
-//|     def __init__(self, key_num: int=0, pressed: bool=True) -> None:
+//|     def __init__(self, key_number: int=0, pressed: bool=True) -> None:
 //|         """Create a key transition event, which reports a key-pressed or key-released transition.
 //|
-//|         :param int key_num: the key number
+//|         :param int key_number: the key number
 //|         :param bool pressed: ``True`` if the key was pressed; ``False`` if it was released.
 //|         """
 //|         ...
 //|
-
 STATIC mp_obj_t keypad_event_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     keypad_event_obj_t *self = m_new_obj(keypad_event_obj_t);
     self->base.type = &keypad_event_type;
-    enum { ARG_key_num, ARG_pressed };
+    enum { ARG_key_number, ARG_pressed };
     static const mp_arg_t allowed_args[] = {
-        { MP_QSTR_key_num, MP_ARG_INT, {.u_int = 0} },
+        { MP_QSTR_key_number, MP_ARG_INT, {.u_int = 0} },
         { MP_QSTR_pressed, MP_ARG_BOOL, {.u_bool = true} },
     };
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
     mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
-    const mp_uint_t key_num = (mp_uint_t)mp_arg_validate_int_min(args[ARG_key_num].u_int, 0, MP_QSTR_key_num);
+    const mp_uint_t key_number =
+        (mp_uint_t)mp_arg_validate_int_min(args[ARG_key_number].u_int, 0, MP_QSTR_key_number);
 
-    common_hal_keypad_event_construct(self, key_num, args[ARG_pressed].u_bool);
+    common_hal_keypad_event_construct(self, key_number, args[ARG_pressed].u_bool);
     return MP_OBJ_FROM_PTR(self);
 }
 
-//|     key_num: int
+//|     key_number: int
 //|     """The key number."""
 //|
-STATIC mp_obj_t keypad_event_get_key_num(mp_obj_t self_in) {
+STATIC mp_obj_t keypad_event_get_key_number(mp_obj_t self_in) {
     keypad_event_obj_t *self = MP_OBJ_TO_PTR(self_in);
-    return MP_OBJ_NEW_SMALL_INT(common_hal_keypad_event_get_key_num(self));
+    return MP_OBJ_NEW_SMALL_INT(common_hal_keypad_event_get_key_number(self));
 }
-MP_DEFINE_CONST_FUN_OBJ_1(keypad_event_get_key_num_obj, keypad_event_get_key_num);
+MP_DEFINE_CONST_FUN_OBJ_1(keypad_event_get_key_number_obj, keypad_event_get_key_number);
 
-const mp_obj_property_t keypad_event_key_num_obj = {
+const mp_obj_property_t keypad_event_key_number_obj = {
     .base.type = &mp_type_property,
-    .proxy = {(mp_obj_t)&keypad_event_get_key_num_obj,
+    .proxy = {(mp_obj_t)&keypad_event_get_key_number_obj,
               MP_ROM_NONE,
               MP_ROM_NONE},
 };
@@ -111,7 +111,7 @@ const mp_obj_property_t keypad_event_released_obj = {
 };
 
 //|     def __eq__(self, other: object) -> bool:
-//|         """Two `Event` objects are equal if their `key_num`
+//|         """Two `Event` objects are equal if their `key_number`
 //|         and `pressed`/`released` values are equal.
 //|         """
 //|         ...
@@ -123,10 +123,11 @@ STATIC mp_obj_t keypad_event_binary_op(mp_binary_op_t op, mp_obj_t lhs_in, mp_ob
                 keypad_event_obj_t *lhs = MP_OBJ_TO_PTR(lhs_in);
                 keypad_event_obj_t *rhs = MP_OBJ_TO_PTR(rhs_in);
                 return mp_obj_new_bool(
-                    (common_hal_keypad_event_get_key_num(lhs) ==
-                        common_hal_keypad_event_get_key_num(rhs)) &&
+                    (common_hal_keypad_event_get_key_number(lhs) ==
+                        common_hal_keypad_event_get_key_number(rhs)) &&
                     (common_hal_keypad_event_get_pressed(lhs) ==
-                        common_hal_keypad_event_get_pressed(rhs)));
+                        common_hal_keypad_event_get_pressed(rhs))
+                    );
             } else {
                 return mp_const_false;
             }
@@ -144,9 +145,9 @@ STATIC mp_obj_t keypad_event_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     keypad_event_obj_t *self = MP_OBJ_TO_PTR(self);
     switch (op) {
         case MP_UNARY_OP_HASH: {
-            const mp_int_t key_num = common_hal_keypad_event_get_key_num(self);
+            const mp_int_t key_number = common_hal_keypad_event_get_key_number(self);
             const bool pressed = common_hal_keypad_event_get_pressed(self);
-            return MP_OBJ_NEW_SMALL_INT((pressed << 15) + key_num);
+            return MP_OBJ_NEW_SMALL_INT((pressed << 15) + key_number);
         }
         default:
             return MP_OBJ_NULL; // op not supported
@@ -155,16 +156,16 @@ STATIC mp_obj_t keypad_event_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
 
 STATIC void keypad_event_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
     keypad_event_obj_t *self = MP_OBJ_TO_PTR(self_in);
-    mp_printf(print, "<Event: keynum %d %s>",
-        common_hal_keypad_event_get_key_num(self),
+    mp_printf(print, "<Event: key_number %d %s>",
+        common_hal_keypad_event_get_key_number(self),
         common_hal_keypad_event_get_pressed(self) ? "pressed" : "released");
 }
 
 STATIC const mp_rom_map_elem_t keypad_event_locals_dict_table[] = {
     // Properties
-    { MP_ROM_QSTR(MP_QSTR_key_num),  MP_ROM_PTR(&keypad_event_key_num_obj) },
-    { MP_ROM_QSTR(MP_QSTR_pressed),  MP_ROM_PTR(&keypad_event_pressed_obj) },
-    { MP_ROM_QSTR(MP_QSTR_released), MP_ROM_PTR(&keypad_event_released_obj) },
+    { MP_ROM_QSTR(MP_QSTR_key_number), MP_ROM_PTR(&keypad_event_key_number_obj) },
+    { MP_ROM_QSTR(MP_QSTR_pressed),    MP_ROM_PTR(&keypad_event_pressed_obj) },
+    { MP_ROM_QSTR(MP_QSTR_released),   MP_ROM_PTR(&keypad_event_released_obj) },
 };
 STATIC MP_DEFINE_CONST_DICT(keypad_event_locals_dict, keypad_event_locals_dict_table);
 

shared-bindings/keypad/Event.h

@@ -32,10 +32,9 @@
 
 extern const mp_obj_type_t keypad_event_type;
 
-void common_hal_keypad_event_construct(keypad_event_obj_t *self, mp_uint_t key_num, bool pressed);
-mp_int_t common_hal_keypad_event_get_key_num(keypad_event_obj_t *self);
+void common_hal_keypad_event_construct(keypad_event_obj_t *self, mp_uint_t key_number, bool pressed);
+mp_int_t common_hal_keypad_event_get_key_number(keypad_event_obj_t *self);
 bool common_hal_keypad_event_get_pressed(keypad_event_obj_t *self);
 bool common_hal_keypad_event_get_released(keypad_event_obj_t *self);
 
-
 #endif // MICROPY_INCLUDED_SHARED_BINDINGS_KEYPAD_EVENT__H

shared-bindings/keypad/EventQueue.c

@@ -24,6 +24,7 @@
  * THE SOFTWARE.
  */
 
+#include "py/objproperty.h"
 #include "py/runtime.h"
 #include "shared-bindings/keypad/Event.h"
 #include "shared-bindings/keypad/EventQueue.h"
@@ -36,50 +37,50 @@
 //|     """
 //|     ...
 
-//|     def next(self) -> Optional[Event]:
+//|     def get(self) -> Optional[Event]:
 //|         """Return the next key transition event. Return ``None`` if no events are pending.
 //|
 //|         Note that the queue size is limited; see ``max_events`` in the constructor of
 //|         a scanner such as `Keys` or `KeyMatrix`.
-//|         If a new event arrives when the queue is full, the oldest event is discarded.
+//|         If a new event arrives when the queue is full, the queue is cleared, and
+//|         `overflowed` is set to ``True``.
 //|
 //|         :return: the next queued key transition `Event`
 //|         :rtype: Optional[Event]
 //|         """
 //|         ...
 //|
-STATIC mp_obj_t keypad_eventqueue_next(mp_obj_t self_in) {
+STATIC mp_obj_t keypad_eventqueue_get(mp_obj_t self_in) {
     keypad_eventqueue_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
-    return common_hal_keypad_eventqueue_next(self);
+    return common_hal_keypad_eventqueue_get(self);
 }
-MP_DEFINE_CONST_FUN_OBJ_1(keypad_eventqueue_next_obj, keypad_eventqueue_next);
+MP_DEFINE_CONST_FUN_OBJ_1(keypad_eventqueue_get_obj, keypad_eventqueue_get);
 
-//|     def store_next(self, event: Event) -> bool:
+//|     def get_into(self, event: Event) -> bool:
 //|         """Store the next key transition event in the supplied event, if available,
 //|         and return ``True``.
 //|         If there are no queued events, do not touch ``event`` and return ``False``.
 //|
-//|         The advantage of this method over ``next()`` is that it does not allocate storage.
+//|         The advantage of this method over ``get()`` is that it does not allocate storage.
 //|         Instead you can reuse an existing ``Event`` object.
 //|
 //|         Note that the queue size is limited; see ``max_events`` in the constructor of
 //|         a scanner such as `Keys` or `KeyMatrix`.
-//|         If a new event arrives when the queue is full, the oldest event is discarded.
 //|
 //|         :return ``True`` if an event was available and stored, ``False`` if not.
 //|         :rtype: bool
 //|         """
 //|         ...
 //|
-STATIC mp_obj_t keypad_eventqueue_store_next(mp_obj_t self_in, mp_obj_t event_in) {
+STATIC mp_obj_t keypad_eventqueue_get_into(mp_obj_t self_in, mp_obj_t event_in) {
     keypad_eventqueue_obj_t *self = MP_OBJ_TO_PTR(self_in);
 
     keypad_event_obj_t *event = MP_OBJ_TO_PTR(mp_arg_validate_type(event_in, &keypad_event_type, MP_QSTR_event));
 
-    return mp_obj_new_bool(common_hal_keypad_eventqueue_store_next(self, event));
+    return mp_obj_new_bool(common_hal_keypad_eventqueue_get_into(self, event));
 }
-MP_DEFINE_CONST_FUN_OBJ_2(keypad_eventqueue_store_next_obj, keypad_eventqueue_store_next);
+MP_DEFINE_CONST_FUN_OBJ_2(keypad_eventqueue_get_into_obj, keypad_eventqueue_get_into);
 
 //|     def clear(self) -> None:
 //|         """Clear any queued key transition events.
@@ -117,10 +118,36 @@ STATIC mp_obj_t keypad_eventqueue_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     }
 }
 
+//|     overflowed: bool
+//|     """``True`` if an event could not be added to the event queue because it was full.
+//|     When this happens, the event queue is cleared.
+//|     The `overflowed` flag is persistent. Reset it by setting it to ``False``.
+//|     """
+//|
+STATIC mp_obj_t keypad_eventqueue_get_overflowed(mp_obj_t self_in) {
+    keypad_eventqueue_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    return mp_obj_new_bool(common_hal_keypad_eventqueue_get_overflowed(self));
+}
+MP_DEFINE_CONST_FUN_OBJ_1(keypad_eventqueue_get_overflowed_obj, keypad_eventqueue_get_overflowed);
+
+STATIC mp_obj_t keypad_eventqueue_set_overflowed(mp_obj_t self_in, mp_obj_t overflowed_in) {
+    keypad_eventqueue_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    common_hal_keypad_eventqueue_set_overflowed(self, mp_obj_is_true(overflowed_in));
+    return MP_ROM_NONE;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(keypad_eventqueue_set_overflowed_obj, keypad_eventqueue_set_overflowed);
+
+const mp_obj_property_t keypad_eventqueue_overflowed_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&keypad_eventqueue_get_overflowed_obj,
+              (mp_obj_t)&keypad_eventqueue_set_overflowed_obj,
+              MP_ROM_NONE},
+};
+
 STATIC const mp_rom_map_elem_t keypad_eventqueue_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_clear),       MP_ROM_PTR(&keypad_eventqueue_clear_obj) },
-    { MP_ROM_QSTR(MP_QSTR_next),        MP_ROM_PTR(&keypad_eventqueue_next_obj) },
-    { MP_ROM_QSTR(MP_QSTR_store_next),  MP_ROM_PTR(&keypad_eventqueue_store_next_obj) },
+    { MP_ROM_QSTR(MP_QSTR_get),        MP_ROM_PTR(&keypad_eventqueue_get_obj) },
+    { MP_ROM_QSTR(MP_QSTR_get_into),  MP_ROM_PTR(&keypad_eventqueue_get_into_obj) },
 };
 
 STATIC MP_DEFINE_CONST_DICT(keypad_eventqueue_locals_dict, keypad_eventqueue_locals_dict_table);

shared-bindings/keypad/EventQueue.h

@@ -36,7 +36,10 @@ void common_hal_keypad_eventqueue_construct(keypad_eventqueue_obj_t *self, size_
 
 void common_hal_keypad_eventqueue_clear(keypad_eventqueue_obj_t *self);
 size_t common_hal_keypad_eventqueue_get_length(keypad_eventqueue_obj_t *self);
-mp_obj_t common_hal_keypad_eventqueue_next(keypad_eventqueue_obj_t *self);
-bool common_hal_keypad_eventqueue_store_next(keypad_eventqueue_obj_t *self, keypad_event_obj_t *event);
+mp_obj_t common_hal_keypad_eventqueue_get(keypad_eventqueue_obj_t *self);
+bool common_hal_keypad_eventqueue_get_into(keypad_eventqueue_obj_t *self, keypad_event_obj_t *event);
+
+bool common_hal_keypad_eventqueue_get_overflowed(keypad_eventqueue_obj_t *self);
+void common_hal_keypad_eventqueue_set_overflowed(keypad_eventqueue_obj_t *self, bool overflowed);
 
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_KEYPAD_EVENTQUEUE_H