Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

Signals, callbacks, timers, and alarms

Brew MP uses a single-threaded UI model that allows for cooperative multitasking on this thread. Resources are limited on Brew MP devices, so this thread is monitored by an internal watchdog device to make sure function calls do not block the thread. You can think of the thread as a dispatch loop, where functions are passed to be processed and on very short intervals the return values are passed back to the calling function. If a function makes a call that takes time to process, the watchdog timer shuts down the application. This typically occurs after approximately 30 seconds. To prevent this blocking situation, signals or callbacks can be used to monitor the dispatch loop for return of the calling function. Applications must use non-blocking calls to avoid locking the device. Signals or callbacks provide a mechanism for processing without blocking calls. In Brew MP there are only separate threads for background thread applications. Foreground UI applications are co-operative threaded.

Signals

Signals are notification objects sent within a process or across process boundaries that provide a method of inter-process communication. For more information on signals, see the OS Services Technology Guide for Developers on the Brew MP website.

Callbacks

A callback is executable code (a function) that is passed as an argument to other code, which allows one software component to call a function defined in another software component. In Brew MP, it is used as a notification mechanism. Instead of blocking the dispatch loop for data to be available, the application can register a callback function and return control back to the dispatcher. When the data become available, the callback function is called and the application can resume its operation. This mechanism is only suitable when it's safe to pass the callback function pointer to the registering function.

Timers

Timers perform an action when a specific amount of time has passed. These time periods are typically short (seconds or milliseconds). Timers are callback-based, and each timer is only triggered once. Users must reset the timer if they want it to repeat. This is usually done inside the callback function itself if a repeating timer is needed. The watchdog timer resets the device if functions don't return in a timely manner.

The AEE Shell's timer facility is used by a currently instantiated application (that is, an application whose reference count is non zero) to perform an action when a specified amount of time has passed. You can use AEE Shell's alarm functions to obtain notification when longer time periods have passed, even when your application is not currently instantiated.

The following steps demonstrate an example of using a timer for animation:

  1. Set the timer.
  2. When a function is called, draw the graphics, then set another timer.
  3. Repeat the behavior for smooth animation.

The same timer and animation routine would automatically work on a faster CPU, without any recoding on your part.

The following are common timer functions:

  • ISHELL_SetTimer()
  • ISHELL_CancelTimer()
  • ISHELL_GetTimerExpiration()

For MOD1 applications, timer functionality is found in ISysTimer.

Alarms

Alarms allow for notification when time reaches a specific value. If an application is not running, Brew MP starts it, then sends it the alarm event. Alarms are typically used when the time of notification is in the distant future, such as calendar alarms that can be used to alert the user when the time of a calendar appointment is about to be reached. Each alarm only triggers once.

The AEE Shell's alarm functions enable an application to be notified when the current time reaches a specified value. Unlike timers, which can only be active while your application is running, you can receive notification that an alarm has expired even when your application is not running.

Note that like timers, alarms do not repeat.

The following are common alarm functions:

  • ISHELL_SetAlarm()
  • ISHELL_CancelAlarm()

Using callbacks with timers

  1. Create a function prototype for your callback function.
  2. Call ISHELL_SetTimer() with the address of the callback function and a pointer to an application-specific data structure. For example:
     ISHELL_SetTimer (pMe -> IShell , TIMER_VAL, (PFNNOTIFY) MyFunc , pMe);
  3. When the timer expires, the shell calls the callback function.

Canceling timers

An individual timer can be cancelled with ISHELL_CancelTimer, as follows:

ISHELL_CancelTimer (pMe -> pIShell, (PFNNOTIFY) MyFunc, pMe);

All timers with the same data pointer can be canceled by passing NULL as the function pointer, as follows:

 ISHELL_CancelTimer (pMe -> pIShell, NULL, pMe);

AEECallback

AEECallback is recommended over function pointers alone. AEECallback is a structure that contains a function pointer, a data pointer, and other bookkeeping data and this structure can be passed quite easily. Much of the bookkeeping data is instantiated by Brew MP and should not be directly accessed by your application.

To initialize the AEECallback, call the CALLBACK_Init() method, passing in a pointer to the structure and a pointer to your callback function, as shown in the code below:

CALLBACK_Init (& pMe -> myCallBack, (PFNNOTIFY) MyFunc, pMe );

Note that this AEECallBack structure should remain valid throughout the asynchronous request to ensure that the function pointer and data are available. The CALLBACK_Cancel() macro can be used to cancel the callback, such as in the case of suspend events. This macro takes a pointer to an AEECallback structure.

The following code fragment shows the initialization of a callback structure AEECallback named myCallBack, which is a member of the applet struct. The structure is initialized using the CALLBACK_INIT() function, marking MyFunc as the function to call when task processing is returned to the application. When the timer is set using ISHELL_SetTimerEx(), the callback is set as the third parameter.

//In app struct
AEECallback myCallBack;

// MyFunc is a function defined in your application
// pMe is the pointer to your application struct

CALLBACK_Init(&pMe->myCallBack, (PFNNOTIFY)MyFunc, pMe);
ISHELL_SetTimerEx(pMe->pIShell, TIMER_VAL, &pMe->myCallBack);

For more information, see AEECallback in the http://developer.brewmp.com/reference/api-all.