Software Timer
Categories:
4 minute read
Overview
The software timer is implemented based on the scheduler’s tick timer task, so the minimum time precision is the tick timer’s interrupt frequency. A software timer can be one-shot or periodic.
Software Timer Object and Object Descriptor
The software timer object is a derived class of the XWOS Object struct xwos_object. Similarly, the software timer object also uses the software timer object descriptor xwos_swt_d to solve the problems of validity and identity verification.
The software timer object descriptor consists of a pointer to the software timer object and a tag:
typedef struct {
struct xwos_swt * swt; /**< Pointer to the software timer object */
xwsq_t tik; /**< Tag */
} xwos_swt_d;
When referencing an object through the object descriptor, first check whether the value of obj->magic is 0x58574F53U, which confirms that the pointer obj points to a valid XWOS object. Then compare the tags obj->tik and tik to see if they are equal, which confirms the identity of the object. Because the object’s tik is globally unique, when the object is released, its tik is destructed to 0 by the destructor. When a memory address is reconstructed as a new object, its tik will definitely be inconsistent with the tik in the object descriptor.
Software Timer Initialization, Destruction, Dynamic Creation, and Deletion
Static Initialization and Destruction
- Static initialization:
xwos_swt_init()- Static means that the user pre-defines thread structure objects, which are allocated memory by the compiler at compile time.
- Destroy statically initialized software timer:
xwos_swt_fini()
Dynamic Creation and Deletion
- Dynamic creation:
xwos_swt_create()- Dynamic means that at runtime, the program allocates memory via a memory allocation function and constructs the object on the allocated memory.
- Delete dynamically created software timer:
xwos_swt_delete()
Software Timer Flags
When initializing or creating a software timer, flags need to be specified:
XWOS_SWT_FLAG_NULL: No flags, placeholder, also indicates the timer is one-shot.XWOS_SWT_FLAG_RESTART: The timer is periodic, i.e., it automatically restarts after timeout.
Starting the Software Timer
After the software timer is initialized or created, it can be started using xwos_swt_start().
When starting, the start time, period, and callback function xwos_swt_f must be specified.
Software Timer Callback Function
When the software timer times out, its callback function xwos_swt_f is called. Its prototype is defined as:
typedef void(* xwos_swt_f) (struct xwos_swt *, void *)
The first parameter is a pointer to the software timer itself, and the second parameter is the callback parameter specified in xwos_swt_start().
The software timer callback function runs in the tick timer task:
- When bottom half (BH) is enabled, the software timer callback function runs in the bottom half (BH);
- When bottom half (BH) is disabled, the software timer callback function runs in interrupt context.
Regardless of whether it runs in bottom half (BH) or interrupt context, the software timer callback function must not use any API that causes sleeping or blocking.
Stopping the Software Timer
Users can stop a started software timer via xwos_swt_stop().
For a software timer that has not been started, this function xwos_swt_stop() only returns an error code and does not cause any destructive effects.
Lifecycle Management of Software Timer Objects
The base class of the software timer object is the XWOS Object struct xwos_object. The software timer object also has two sets of CAPI for lifecycle management:
-
Using object pointer to access lifecycle management CAPI: requires ensuring that the object is definitely valid when calling the CAPI, and that there is no scenario of release-then-allocate as another object.
xwos_swt_grab(): Increase reference count.xwos_swt_put(): Decrease reference count. When the reference count reaches 0, invoke the garbage collection function to release the object.
-
Using object descriptor to access lifecycle management CAPI: used when the user cannot guarantee that the object is definitely valid or cannot guarantee that the object has not become another object.
xwos_swt_acquire(): Confirm the object is valid and legitimate via the object descriptor, then increase reference count.xwos_swt_release(): Confirm the object is valid and legitimate via the object descriptor, then decrease reference count. When the reference count reaches 0, invoke the garbage collection function to release the object.