SFBTicker Class Reference

The short-term, high-resolution profiling information maintained by the core. More...

#include <SFBTicker.h>


Public Member Functions

void pushTime (u32 code)
 Begin assigning time to code -- which should be one of the SFBTickerCategories -- while using an internal stack to remember where time was previously being assigned.
void popTime ()
 Undo the effect of the most recent pushTime().
void pushTimeISR (u32 code)
 Can be used instead of pushTime(u32) when the caller is certain that interrupts are already disabled.
void popTimeISR ()
 Can be used instead of popTime() when the caller is certain that interrupts are already disabled.
u32 getUsec (u32 category)
 Return the number of microseconds assigned to category since the last reset().
u32 getTotalUsec ()
 Return the total number of microseconds since the last call on reset.
void reset (u32 intoState=TICKER_BACKGROUND)
 Reset all profiling information, setting all profiling counts to zero.


Detailed Description

The short-term, high-resolution profiling information maintained by the core.

(See SFBProfile for longer-term, lower-resolution data). The core gathers microsecond-resolution data about where time is being spent, and assigns each microsecond to one of the SFBTickerCategories as appropriate. There is no 'double billing'; for example, microseconds spent in the loop() function are assigned to TICKER_BACKGROUND, but if loop() calls delay() which in turn calls, say, a packet handler, then the microseconds taken by that packet handler are assigned to TICKER_PACKET_HANDLER and not to TICKER_BACKGROUND. Similarly, microseconds spent at interrupt level is assigned only to TICKER_SERIAL_ISR or TICKER_OTHER_ISR, not also to whatever the system was doing when the interrupt hit.

The SFBTicker system is designed to be lightweight while supporting microsecond accuracy, so all accounting is performed in u32, which means that internal profiling counters may begin to overflow after only a bit over an hour of runtime. In many cases it may be more convenient to use the SFBProfile mechanism in concert with SFBTicker, which provides millisecond resolution valid over a month and half of runtime.

Since:
0.9.13

Member Function Documentation

u32 SFBTicker::getTotalUsec (  )  [inline]

Return the total number of microseconds since the last call on reset.

This value will be inaccurate if more than about an hour has elapsed since the last reset().

u32 SFBTicker::getUsec ( u32  category  ) 

Return the number of microseconds assigned to category since the last reset().

This value may be inaccurate if more than about an hour has elapsed since the last call on reset().

Parameters:
category The SFBTickerCategories category to access.
Blinks:
E_API_MAX_RANGE if category is not one of the SFBTickerCategories values, 0..MAX_TICKERS-1
Examples:
profile1.cpp.

void SFBTicker::popTime (  )  [inline]

Undo the effect of the most recent pushTime().

Stop assigning time to the category most-recently passed to pushTime(), and resume assigning time to whatever category had been active before that.

For correct results, pushTime() and popTime() calls must be properly matched. An popTime() call without a corresponding pushTime(), or a popTime() when the internal stack is empty, will cause the profiling results to be incorrect but will not overwise affect or harm execution.

Examples:
profile3.cpp.

void SFBTicker::popTimeISR (  )  [inline]

Can be used instead of popTime() when the caller is certain that interrupts are already disabled.

If this method is used when interrupts are enabled, Ticker results (sooner or later) will be incorrect.

void SFBTicker::pushTime ( u32  code  )  [inline]

Begin assigning time to code -- which should be one of the SFBTickerCategories -- while using an internal stack to remember where time was previously being assigned.

From sketch level, pushTime() should generally only be used with code values of TICKER_SKETCH0, TICKER_SKETCH1, or TICKER_SKETCH2, to begin assigning time to one of those categories which are reserved for sketch purposes.

Note that the internal stack used by pushTime and popTime can contain up to ten entries before it will overflow, and up to three entries may already be in use when sketch code is entered. For proper accuracy, sketch code should avoid nesting pushTime() calls deeper than five or six levels. Overflowing the SFBTicker stack will cause the profiling results to be incorrect but will not overwise affect or harm execution.

Parameters:
code The SFBTickerCategories value to use. Note that for efficiency, pushTime does not die blinking if an invalid code is passed; instead, the passed value is converted to some valid SFBTickerCategories by an unspecified mechanism.
Examples:
profile3.cpp.

void SFBTicker::pushTimeISR ( u32  code  )  [inline]

Can be used instead of pushTime(u32) when the caller is certain that interrupts are already disabled.

If this method is used when interrupts are enabled, Ticker results (sooner or later) will be incorrect.

void SFBTicker::reset ( u32  intoState = TICKER_BACKGROUND  ) 

Reset all profiling information, setting all profiling counts to zero.

The profiling stack is reinitialized as if an indefinite number of pushTime(TICKER_BACKGROUND) calls had been performed followed by a pushTime(intoState) call, so if it is desired to reset the Ticker from inside an alarm or packet handler, then Ticker.reset(TICKER_ALARM_HANDLER) or Ticker.reset(TICKER_PACKET_HANDLER), respectively, will produce the most accurate counts.

Parameters:
intoState (Optional, default value TICKER_BACKGROUND) The SFBTickerCategories category to place on the top of the Ticker stack.
Blinks:
E_API_MAX_RANGE if intoState is not one of the SFBTickerCategories values, 0..MAX_TICKERS-1
Examples:
profile1.cpp.


The documentation for this class was generated from the following files:

Generated on Fri Apr 22 06:57:31 2011 for SFB by doxygen 1.5.9