Revision 41:da05ec75cd5d, committed 2016-07-13

Comitter:

LancasterUniversity

Date:

Wed Jul 13 12:18:21 2016 +0100

Parent:

40:948486a56c9d

Child:

42:e2869e0fa366

Commit message:

Synchronized with git rev e0369cab
Author: Joe Finney
microbit: Removed legacy isIdleCallbackNeeded() method. [issue #138]

This function has been deprecated, so now removed for v2.0.0 release.

Changed in this revision

--- a/inc/core/MicroBitComponent.h	Wed Jul 13 12:18:20 2016 +0100
+++ b/inc/core/MicroBitComponent.h	Wed Jul 13 12:18:21 2016 +0100
@@ -81,23 +81,30 @@
   *
   * All components should inherit from this class.
   *
-  * If a component requires regular updates, then you should add the component
-  * to the systemTick and idleTick queues.
+  * If a component requires regular updates, then that component can be added to the 
+  * to the systemTick and/or idleTick queues. This provides a simple, extensible mechanism
+  * for code that requires periodic/occasional background processing but does not warrant
+  * the complexity of maintaining its own thread. 
+  *
+  * Two levels of support are available. 
   *
-  * The system timer will call systemTick() once the component has been added to
-  * the array of system components using system_timer_add_component. This callback
-  * will be in interrupt context.
+  * systemTick() provides a periodic callback during the
+  * micro:bit's system timer interrupt. This provides a guaranteed periodic callback, but in interrupt context
+  * and is suitable for code with lightweight processing requirements, but strict time constraints.
+  * 
+  * idleTick() provides a periodic callback whenever the scheduler is idle. This provides occasional, callbacks
+  * in the main thread context, but with no guarantees of frequency. This is suitable for non-urgent background tasks.
   *
-  * The idle thread will call idleTick() once the component has been added to the array
-  * of idle components using fiber_add_idle_component. Updates are determined by
-  * the isIdleCallbackNeeded() member function.
+  * Components wishing to use these facilities should override the systemTick and/or idleTick functions defined here, and
+  * register their components using system_timer_add_component() fiber_add_idle_component() respectively.
+  *
   */
 class MicroBitComponent
 {
     protected:
 
-    uint16_t id;                    // Event Bus ID
-    uint8_t status;                 // keeps track of various component state, and also indicates if data is ready.
+    uint16_t id;                    // Event Bus ID of this component
+    uint8_t status;                 // Component defined state.
 
     public:
 
@@ -115,29 +122,16 @@
       * the array of system components using system_timer_add_component. This callback
       * will be in interrupt context.
       */
-    virtual void systemTick(){
-
+    virtual void systemTick()
+    {
     }
 
     /**
       * The idle thread will call this member function once the component has been added to the array
-      * of idle components using fiber_add_idle_component. Updates are determined by
-      * the isIdleCallbackNeeded() member function.
+      * of idle components using fiber_add_idle_component. 
       */
     virtual void idleTick()
     {
-
-    }
-
-    /**
-      * When added to the idleThreadComponents array, this function will be called to determine
-      * if and when data is ready.
-      *
-      * @note override this if you want to request to be scheduled as soon as possible.
-      */
-    virtual int isIdleCallbackNeeded()
-    {
-        return 0;
     }
 
     /**
@@ -149,4 +143,4 @@
     }
 };
 
-#endif
+#endif
\ No newline at end of file

--- a/inc/core/MicroBitFiber.h	Wed Jul 13 12:18:20 2016 +0100
+++ b/inc/core/MicroBitFiber.h	Wed Jul 13 12:18:21 2016 +0100
@@ -341,41 +341,16 @@
   * Adds a component to the array of idle thread components, which are processed
   * when the run queue is empty.
   *
-  * The system timer will poll isIdleCallbackNeeded on each component to determine
-  * if the scheduler should schedule the idle_task imminently.
-  *
   * @param component The component to add to the array.
-  *
   * @return MICROBIT_OK on success or MICROBIT_NO_RESOURCES if the fiber components array is full.
-  *
-  * @code
-  * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
-  *
-  * // heap allocated - otherwise it will be paged out!
-  * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
-  *
-  * fiber_add_idle_component(accelerometer);
-  * @endcode
   */
 int fiber_add_idle_component(MicroBitComponent *component);
 
 /**
-  * Remove a component from the array of idle thread components
-  *
-  * @param component The component to remove from the idle component array.
-  *
-  * @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
+  * remove a component from the array of idle thread components
   *
-  * @code
-  * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
-  *
-  * // heap allocated - otherwise it will be paged out!
-  * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
-  *
-  * fiber_add_idle_component(accelerometer);
-  *
-  * fiber_remove_idle_component(accelerometer);
-  * @endcode
+  * @param component the component to remove from the idle component array.
+  * @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
   */
 int fiber_remove_idle_component(MicroBitComponent *component);
 
@@ -398,4 +373,4 @@
 extern "C" void save_register_context(Cortex_M0_TCB *tcb);
 extern "C" void restore_register_context(Cortex_M0_TCB *tcb);
 
-#endif
+#endif
\ No newline at end of file

--- a/inc/drivers/MicroBitAccelerometer.h	Wed Jul 13 12:18:20 2016 +0100
+++ b/inc/drivers/MicroBitAccelerometer.h	Wed Jul 13 12:18:21 2016 +0100
@@ -377,13 +377,6 @@
     virtual void idleTick();
 
     /**
-      * Returns 0 or 1. 1 indicates data is waiting to be read, zero means data is not ready to be read.
-      *
-      * We check if any data is ready for reading by checking the interrupt flag on the accelerometer.
-      */
-    virtual int isIdleCallbackNeeded();
-
-    /**
       * Destructor for MicroBitButton, where we deregister this instance from the array of fiber components.
       */
     ~MicroBitAccelerometer();

--- a/inc/drivers/MicroBitCompass.h	Wed Jul 13 12:18:20 2016 +0100
+++ b/inc/drivers/MicroBitCompass.h	Wed Jul 13 12:18:21 2016 +0100
@@ -434,11 +434,6 @@
     void clearCalibration();
 
     /**
-      * Returns 0 or 1. 1 indicates data is waiting to be read, zero means data is not ready to be read.
-      */
-    virtual int isIdleCallbackNeeded();
-
-    /**
       * Destructor for MicroBitCompass, where we deregister this instance from the array of fiber components.
       */
     ~MicroBitCompass();
@@ -515,4 +510,4 @@
     void init(uint16_t id, uint16_t address);
 };
 
-#endif
+#endif
\ No newline at end of file

--- a/inc/drivers/MicroBitMessageBus.h	Wed Jul 13 12:18:20 2016 +0100
+++ b/inc/drivers/MicroBitMessageBus.h	Wed Jul 13 12:18:21 2016 +0100
@@ -176,13 +176,6 @@
       * We then continue processing events until something appears on the runqueue.
       */
     virtual void idleTick();
-
-    /**
-      * Indicates whether or not we have any background work to do.
-      *
-      * @return 1 if there are any events waitingto be processed, 0 otherwise.
-      */
-    virtual int isIdleCallbackNeeded();
 };
 
-#endif
+#endif
\ No newline at end of file

--- a/inc/drivers/MicroBitThermometer.h	Wed Jul 13 12:18:20 2016 +0100
+++ b/inc/drivers/MicroBitThermometer.h	Wed Jul 13 12:18:21 2016 +0100
@@ -160,13 +160,6 @@
       */
     virtual void idleTick();
 
-    /**
-      * Indicates if we'd like some processor time to sense the temperature.
-      *
-      * @returns 1 if we'd like some processor time, 0 otherwise.
-      */
-    virtual int isIdleCallbackNeeded();
-
     private:
 
     /**
@@ -177,4 +170,4 @@
     int isSampleNeeded();
 };
 
-#endif
+#endif
\ No newline at end of file

--- a/source/core/MicroBitFiber.cpp	Wed Jul 13 12:18:20 2016 +0100
+++ b/source/core/MicroBitFiber.cpp	Wed Jul 13 12:18:21 2016 +0100
@@ -62,7 +62,7 @@
  */
 static EventModel *messageBus = NULL;
 
-// Array of components which are iterated during idle thread execution, isIdleCallbackNeeded is polled during a systemTick.
+// Array of components which are iterated during idle thread execution.
 static MicroBitComponent* idleThreadComponents[MICROBIT_IDLE_COMPONENTS];
 
 /**
@@ -874,21 +874,8 @@
   * Adds a component to the array of idle thread components, which are processed
   * when the run queue is empty.
   *
-  * The system timer will poll isIdleCallbackNeeded on each component to determine
-  * if the scheduler should schedule the idle_task imminently.
-  *
   * @param component The component to add to the array.
-  *
   * @return MICROBIT_OK on success or MICROBIT_NO_RESOURCES if the fiber components array is full.
-  *
-  * @code
-  * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
-  *
-  * // heap allocated - otherwise it will be paged out!
-  * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
-  *
-  * fiber_add_idle_component(accelerometer);
-  * @endcode
   */
 int fiber_add_idle_component(MicroBitComponent *component)
 {
@@ -906,22 +893,10 @@
 }
 
 /**
-  * Remove a component from the array of idle thread components
-  *
-  * @param component The component to remove from the idle component array.
-  *
-  * @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
+  * remove a component from the array of idle thread components
   *
-  * @code
-  * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
-  *
-  * // heap allocated - otherwise it will be paged out!
-  * MicroBitAccelerometer* accelerometer = new MicroBitAccelerometer(i2c);
-  *
-  * fiber_add_idle_component(accelerometer);
-  *
-  * fiber_remove_idle_component(accelerometer);
-  * @endcode
+  * @param component the component to remove from the idle component array.
+  * @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previously added.
   */
 int fiber_remove_idle_component(MicroBitComponent *component)
 {

--- a/source/drivers/MicroBitAccelerometer.cpp	Wed Jul 13 12:18:20 2016 +0100
+++ b/source/drivers/MicroBitAccelerometer.cpp	Wed Jul 13 12:18:21 2016 +0100
@@ -711,16 +711,6 @@
 }
 
 /**
-  * Returns 0 or 1. 1 indicates data is waiting to be read, zero means data is not ready to be read.
-  *
-  * We check if any data is ready for reading by checking the interrupt flag on the accelerometer.
-  */
-int MicroBitAccelerometer::isIdleCallbackNeeded()
-{
-    return !int1;
-}
-
-/**
   * Destructor for MicroBitAccelerometer, where we deregister from the array of fiber components.
   */
 MicroBitAccelerometer::~MicroBitAccelerometer()

--- a/source/drivers/MicroBitCompass.cpp	Wed Jul 13 12:18:20 2016 +0100
+++ b/source/drivers/MicroBitCompass.cpp	Wed Jul 13 12:18:21 2016 +0100
@@ -746,16 +746,6 @@
 }
 
 /**
-  * Returns 0 or 1. 1 indicates data is waiting to be read, zero means data is not ready to be read.
-  */
-int MicroBitCompass::isIdleCallbackNeeded()
-{
-    // The MAG3110 raises an interrupt line when data is ready, which we sample here.
-    // The interrupt line is active HI, so simply return the state of the pin.
-    return int1;
-}
-
-/**
   * Destructor for MicroBitCompass, where we deregister this instance from the array of fiber components.
   */
 MicroBitCompass::~MicroBitCompass()

--- a/source/drivers/MicroBitMessageBus.cpp	Wed Jul 13 12:18:20 2016 +0100
+++ b/source/drivers/MicroBitMessageBus.cpp	Wed Jul 13 12:18:21 2016 +0100
@@ -295,16 +295,6 @@
 }
 
 /**
-  * Indicates whether or not we have any background work to do.
-  *
-  * @return 1 if there are any events waitingto be processed, 0 otherwise.
-  */
-int MicroBitMessageBus::isIdleCallbackNeeded()
-{
-    return !(evt_queue_head == NULL);
-}
-
-/**
   * Queues the given event to be sent to all registered recipients.
   *
   * @param evt The event to send.

--- a/source/drivers/MicroBitThermometer.cpp	Wed Jul 13 12:18:20 2016 +0100
+++ b/source/drivers/MicroBitThermometer.cpp	Wed Jul 13 12:18:21 2016 +0100
@@ -182,16 +182,6 @@
 };
 
 /**
-  * Indicates if we'd like some processor time to sense the temperature.
-  *
-  * @returns 1 if we'd like some processor time, 0 otherwise.
-  */
-int MicroBitThermometer::isIdleCallbackNeeded()
-{
-    return isSampleNeeded();
-}
-
-/**
   * Periodic callback from MicroBit idle thread.
   */
 void MicroBitThermometer::idleTick()