API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

AEECALLBACK

Brew Release
Brew MP 1.0.2
See Also
None
Description

AEECallback structures establish a generalized mechanism for scheduling asynchronous callbacks.
When an AEECallback is scheduled, the caller requests some object -- the scheduling object -- that the callback be called at some time in the future, perhaps tied to the occurrence of some event.
AEECallbacks contain the following information:
- Closure: this consists of a function pointer to be called, and a context
pointer to be passed to the function. This is supplied by the owner of the AEECallback when it is constructed using CALLBACK_Init().
- Cancellation data: this information allows the owner of an AEECallback to
cancel the callback -- prevent it from being called -- at any time. Cancellation does not require knowledge of which scheduling object currently holds the AEECallback -- this information is embodied in the AEECallback itself.
- Queueing data: some fields are reserved for use by scheduling objects
to keep track of the AEECallback and what it is waiting on.
An AEECallbacks can be used to wait on only one thing at a time, but can wait on different things at different times. If you call two scheduling functions with the same AEECallback, the second one will cancel the notification scheduled by the first. An object that receives notifications, therefore, will require one AEECallback for each concurrent operation it manages, not necessarily one AEECallback for each type of thing it waits on.
Usage

- An object that requires asynchronous notification of events will contain
one AEECallback for simultaneous pending notification it will wait on.
- When the object is created, each of its AEECallbacks are initialized. For
a context pointer they will use the object instance, and for the callback function they will use an event-specific function.
- When the object is deleted, it must cancel all of its AEECallbacks using
CALLBACK_Cancel(). Canceling an unscheduled callback is harmless. If a callback were to be called after the object is deleted, it would de-reference a dangling pointer (because the object instance itself is the context).
Members
  • pNext: Reserved and the caller should not modify this member, used by the 
             callback handler (callee)
    
  • pmc: Reserved and the caller should not modify this member, used by the 
             callback handler (callee)
    
  • pfnCancel: Pointer to function called by the callback handler if this
                 callback is cancelled. The caller should set this pointer to NULL.
    
  • pCancelData: Data passed to pfnCancel. The caller should not modify
                    this member.
    
  • pfnNotify: This is the callback function that is invoked by the callee. The
               caller must set this pointer in order to be called back when the
               event of interest has occurred.
    
  • pNotifyData: Data to be passed to pfnNotify, the caller must set this
              pointer to the data that must be passed to the pfnNotify function.
    
  • pReserved: Reserved and this member will be used by the callback handler
Definition
  •    typedef struct _AEECallback AEECallback;
       struct _AEECallback
       {
          AEECallback*        pNext;
          void*               pmc;
          CallbackCancelFunc* pfnCancel;
          void*               pCancelData;
          CallbackNotifyFunc* pfnNotify;
          void*               pNotifyData;
          void*               pReserved;
       };
    
Comments
Adhering to the following typical usage will ensure trouble-free AEECallback