libnx  v4.2.0
event.h
Go to the documentation of this file.
1 /**
2  * @file event.h
3  * @brief Kernel-mode event synchronization primitive.
4  * @author plutoo
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../result.h"
10 #include "wait.h"
11 
12 /// Kernel-mode event structure.
13 typedef struct {
14  Handle revent; ///< Read-only event handle
15  Handle wevent; ///< Write-only event handle
16  bool autoclear; ///< Autoclear flag
17 } Event;
18 
19 /// Creates a \ref Waiter for a kernel-mode event.
20 static inline Waiter waiterForEvent(Event* t)
21 {
22  Waiter wait_obj;
23  wait_obj.type = t->autoclear ? WaiterType_HandleWithClear : WaiterType_Handle;
24  wait_obj.handle = t->revent;
25  return wait_obj;
26 }
27 
28 /**
29  * @brief Creates a kernel-mode event.
30  * @param[out] t Pointer to \ref Event structure.
31  * @param[in] autoclear Autoclear flag.
32  * @return Result code.
33  * @warning This is a privileged operation; in normal circumstances applications shouldn't use this function.
34  */
35 Result eventCreate(Event* t, bool autoclear);
36 
37 /**
38  * @brief Loads a kernel-mode event obtained from IPC.
39  * @param[out] t Pointer to \ref Event structure.
40  * @param[in] handle Read-only event handle.
41  * @param[in] autoclear Autoclear flag.
42  */
43 void eventLoadRemote(Event* t, Handle handle, bool autoclear);
44 
45 /**
46  * @brief Closes a kernel-mode event.
47  * @param[in] t Pointer to \ref Event structure.
48  */
49 void eventClose(Event* t);
50 
51 /**
52  * @brief Returns whether an \ref Event is initialized.
53  * @param[in] t Pointer to \ref Event structure.
54  * @return Initialization status.
55  */
56 static inline bool eventActive(Event* t)
57 {
58  return t->revent != INVALID_HANDLE;
59 }
60 
61 /**
62  * @brief Waits on a kernel-mode event.
63  * @param[in] t Pointer to \ref Event structure.
64  * @param[in] timeout Timeout in nanoseconds (pass UINT64_MAX to wait indefinitely).
65  * @return Result code.
66  */
67 Result eventWait(Event* t, u64 timeout);
68 
69 /**
70  * @brief Signals a kernel-mode event.
71  * @param[in] t Pointer to \ref Event structure.
72  * @return Result code.
73  * @note This function only works for events initialized with \ref eventCreate, it doesn't work with events initialized with \ref eventLoadRemote.
74  * @warning This is a privileged operation; in normal circumstances applications shouldn't use this function.
75  */
77 
78 /**
79  * @brief Clears a kernel-mode event.
80  * @param[in] t Pointer to \ref Event structure.
81  * @return Result code.
82  * @note This function shouldn't be used on autoclear events.
83  */
eventActive
static bool eventActive(Event *t)
Returns whether an Event is initialized.
Definition: event.h:56
Event::wevent
Handle wevent
Write-only event handle.
Definition: event.h:15
waiterForEvent
static Waiter waiterForEvent(Event *t)
Creates a Waiter for a kernel-mode event.
Definition: event.h:20
Event
Kernel-mode event structure.
Definition: event.h:13
Event::autoclear
bool autoclear
Autoclear flag.
Definition: event.h:16
INVALID_HANDLE
#define INVALID_HANDLE
Invalid handle.
Definition: types.h:92
wait.h
User mode synchronization primitive waiting operations.
eventClear
Result eventClear(Event *t)
Clears a kernel-mode event.
Waiter
Waiter structure, representing any generic waitable synchronization object; both kernel-mode and user...
Definition: wait.h:36
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
eventLoadRemote
void eventLoadRemote(Event *t, Handle handle, bool autoclear)
Loads a kernel-mode event obtained from IPC.
Result
u32 Result
Function error code result type.
Definition: types.h:44
eventCreate
Result eventCreate(Event *t, bool autoclear)
Creates a kernel-mode event.
Event::revent
Handle revent
Read-only event handle.
Definition: event.h:14
eventFire
Result eventFire(Event *t)
Signals a kernel-mode event.
eventClose
void eventClose(Event *t)
Closes a kernel-mode event.
eventWait
Result eventWait(Event *t, u64 timeout)
Waits on a kernel-mode event.
Handle
u32 Handle
Kernel object handle.
Definition: types.h:43