Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kPeriodic.h
Go to the documentation of this file.
1 /**
2 * @file kPeriodic.h
3 * @brief Declares the kPeriodic class.
4 *
5 * @internal
6 * Copyright (C) 2010-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_PERIODIC_H
11 #define K_API_PERIODIC_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kPeriodic
19 * @extends kObject
20 * @ingroup kApi-Threads
21 * @brief Provides a periodic function call.
22 */
23 //typedef kObject kPeriodic; --forward-declared in kApiDef.x.h
24
25 /** Defines the signature of a callback function to receive timer notifications. */
26 typedef kStatus(kCall *kPeriodicElapsedFx) (kPointer context, kPeriodic timer);
27
28 /**
29 * Constructs a kPeriodic object.
30 *
31 * @public @memberof kPeriodic
32 * @param timer Receives a handle to the constructed object.
33 * @param allocator Memory allocator (or kNULL for default).
34 * @return Operation status.
35 */
36 kFx(kStatus) kPeriodic_Construct(kPeriodic* timer, kAlloc allocator);
37
38 /**
39 * Starts callbacks at the specified period.
40 *
41 * It is safe to call this function from within a timer callback. It is valid to call Start multiple
42 * times without first calling Stop, in order to change the timer period or callback function.
43 *
44 * Each subsequent timer period after the first callback is measured relative to the end
45 * of the previous timer callback.
46 *
47 * @public @memberof kPeriodic
48 * @param timer kPeriodic object.
49 * @param period Callback period, in microseconds.
50 * @param onElapsed Callback function.
51 * @param context User context handle supplied to the callback function.
52 * @return Operation status.
53 */
54 kFx(kStatus) kPeriodic_Start(kPeriodic timer, k64u period, kPeriodicElapsedFx onElapsed, kPointer context);
55
56 /**
57 * Stops timer callbacks.
58 *
59 * It is guaranteed that callbacks are stopped when this function returns. Deadlock can occur
60 * if a timer callback is in progress and is blocked indefinitely. It is safe to call this function
61 * from within a timer callback.
62 *
63 * @public @memberof kPeriodic
64 * @param timer kPeriodic object.
65 * @return Operation status.
66 */
67 kFx(kStatus) kPeriodic_Stop(kPeriodic timer);
68
69 /**
70 * Reports whether periodic timer callbacks are currently enabled.
71 *
72 * Deadlock can occur if a timer callback is in progress and is blocked indefinitely when this
73 * function is called. It is safe to call this function from within a timer callback.
74 *
75 * @public @memberof kPeriodic
76 * @param timer kPeriodic object.
77 * @return Operation status.
78 */
79 kFx(kBool) kPeriodic_Enabled(kPeriodic timer);
80
81 kEndHeader()
82
83 #include <kApi/Threads/kPeriodic.x.h>
84
85 #endif
k64u
Represents a 64-bit unsigned integer.
kPointer
Represents a void pointer.
kPeriodic::kPeriodic_Construct
kStatus kPeriodic_Construct(kPeriodic *timer, kAlloc allocator)
Constructs a kPeriodic object.
kAlloc
Abstract base class for memory allocator types.
kApiDef.h
Essential API declarations.
kPeriodic::kPeriodic_Stop
kStatus kPeriodic_Stop(kPeriodic timer)
Stops timer callbacks.
kStatus
Represents an enumeration of error codes.
kPeriodic::kPeriodic_Start
kStatus kPeriodic_Start(kPeriodic timer, k64u period, kPeriodicElapsedFx onElapsed, kPointer context)
Starts callbacks at the specified period.
kCall
#define kCall
kApi standard function calling convention.
Definition: kApiDef.h:17
kBool
Represents a boolean value.
kPeriodic::kPeriodic_Enabled
kBool kPeriodic_Enabled(kPeriodic timer)
Reports whether periodic timer callbacks are currently enabled.
kPeriodic
Provides a periodic function call.