MySQL 9.1.0
Source Code Documentation
os0event.h
Go to the documentation of this file.
1/*****************************************************************************
2Copyright (c) 1995, 2024, Oracle and/or its affiliates.
3
4This program is free software; you can redistribute it and/or modify it under
5the terms of the GNU General Public License, version 2.0, as published by the
6Free Software Foundation.
7
8This program is designed to work with certain software (including
9but not limited to OpenSSL) that is licensed under separate terms,
10as designated in a particular file or component or in included license
11documentation. The authors of MySQL hereby grant you an additional
12permission to link the program and your derivative works with the
13separately licensed software that they have either included with
14the program or referenced in the documentation.
15
16This program is distributed in the hope that it will be useful, but WITHOUT
17ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
19for more details.
20
21You should have received a copy of the GNU General Public License along with
22this program; if not, write to the Free Software Foundation, Inc.,
2351 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24
25*****************************************************************************/
26
27/** @file include/os0event.h
28 The interface to the operating system condition variables
29
30 Created 2012-09-23 Sunny Bains (split from os0sync.h)
31 *******************************************************/
32
33#ifndef os0event_h
34#define os0event_h
35
36#include <sys/types.h>
37
38#include "univ.i"
39
40// Forward declaration.
41struct os_event;
42typedef struct os_event *os_event_t;
43
44/** Return value of os_event_wait_time() when the time is exceeded */
45constexpr uint32_t OS_SYNC_TIME_EXCEEDED = 1;
46
47#ifndef UNIV_HOTBACKUP
48/**
49Creates an event semaphore, i.e., a semaphore which may just have two states:
50signaled and nonsignaled. The created event is manual reset: it must be reset
51explicitly by calling os_event_reset().
52@return the event handle */
54
55/**
56Sets an event semaphore to the signaled state: lets waiting threads
57proceed. */
58void os_event_set(os_event_t event); /*!< in/out: event to set */
59
61
62/**
63Check if the event is set.
64@return true if set */
65bool os_event_is_set(const os_event_t event); /*!< in: event to set */
66
67/**
68Resets an event semaphore to the non-signaled state. Waiting threads will
69stop to wait for the event.
70The return value should be passed to os_even_wait_low() if it is desired
71that this thread should not wait in case of an intervening call to
72os_event_set() between this os_event_reset() and the
73os_event_wait_low() call. See comments for os_event_wait_low(). */
74int64_t os_event_reset(os_event_t event); /*!< in/out: event to reset */
75
76/**
77Frees an event object. */
78void os_event_destroy(os_event_t &event); /*!< in/own: event to free */
79
80/**
81Waits for an event object until it is in the signaled state.
82
83Typically, if the event has been signalled after the os_event_reset()
84we'll return immediately because event->is_set == true.
85There are, however, situations (e.g.: sync_array code) where we may
86lose this information. For example:
87
88thread A calls os_event_reset()
89thread B calls os_event_set() [event->is_set == true]
90thread C calls os_event_reset() [event->is_set == false]
91thread A calls os_event_wait() [infinite wait!]
92thread C calls os_event_wait() [infinite wait!]
93
94Where such a scenario is possible, to avoid infinite wait, the
95value returned by os_event_reset() should be passed in as
96reset_sig_count. */
97void os_event_wait_low(os_event_t event, /*!< in/out: event to wait */
98 int64_t reset_sig_count); /*!< in: zero or the value
99 returned by previous call of
100 os_event_reset(). */
101
102/** Blocking infinite wait on an event, until signalled.
103@param e - event to wait on. */
104static inline void os_event_wait(os_event_t e) { os_event_wait_low(e, 0); }
105
106/** Waits for an event object until it is in the signaled state or
107a timeout is exceeded. In Unix the timeout is always infinite.
108@param[in,out] event Event to wait for.
109@param[in] timeout Timeout, or std::chrono::microseconds::max().
110@param[in] reset_sig_count Zero or the value returned by previous call of
111os_event_reset().
112@return 0 if success, OS_SYNC_TIME_EXCEEDED if timeout was exceeded */
114 std::chrono::microseconds timeout,
115 int64_t reset_sig_count);
116
117/** Blocking timed wait on an event.
118@param e - event to wait on.
119@param t - timeout */
121 std::chrono::microseconds t) {
122 return os_event_wait_time_low(e, t, 0);
123}
124
125#include "os0event.ic"
126
127/** Initializes support for os_event objects. Must be called once,
128 and before any os_event object is created. */
129void os_event_global_init(void);
130
131/** Deinitializes support for os_event objects. Must be called once,
132 and after all os_event objects are destroyed. After it is called, no
133new os_event is allowed to be created. */
134void os_event_global_destroy(void);
135
136#endif /* !UNIV_HOTBACKUP */
137
138/** A RAII wrapper for os_event_t. */
140 public:
143 other.m_event = nullptr;
144 }
146
147 operator os_event_t() { return m_event; }
148
149 private:
151};
152
153#endif /* !os0event_h */
A RAII wrapper for os_event_t.
Definition: os0event.h:139
~Os_event_t()
Definition: os0event.h:145
os_event_t m_event
Definition: os0event.h:150
Os_event_t(Os_event_t &&other)
Definition: os0event.h:142
Os_event_t()
Definition: os0event.h:141
static bool timeout(bool(*wait_condition)())
Timeout function.
Definition: log0meb.cc:498
void os_event_global_destroy(void)
Deinitializes support for os_event objects.
Definition: os0event.cc:639
os_event_t os_event_create()
Creates an event semaphore, i.e., a semaphore which may just have two states: signaled and nonsignale...
Definition: os0event.cc:528
constexpr uint32_t OS_SYNC_TIME_EXCEEDED
Return value of os_event_wait_time() when the time is exceeded.
Definition: os0event.h:45
void os_event_global_init(void)
Initializes support for os_event objects.
Definition: os0event.cc:614
bool os_event_try_set(os_event_t event)
Definition: os0event.cc:558
void os_event_destroy(os_event_t &event)
Frees an event object.
Definition: os0event.cc:595
ulint os_event_wait_time_low(os_event_t event, std::chrono::microseconds timeout, int64_t reset_sig_count)
Waits for an event object until it is in the signaled state or a timeout is exceeded.
Definition: os0event.cc:573
static ulint os_event_wait_time(os_event_t e, std::chrono::microseconds t)
Blocking timed wait on an event.
Definition: os0event.h:120
void os_event_wait_low(os_event_t event, int64_t reset_sig_count)
Waits for an event object until it is in the signaled state.
Definition: os0event.cc:585
void os_event_set(os_event_t event)
Sets an event semaphore to the signaled state: lets waiting threads proceed.
Definition: os0event.cc:553
bool os_event_is_set(const os_event_t event)
Check if the event is set.
Definition: os0event.cc:545
static void os_event_wait(os_event_t e)
Blocking infinite wait on an event, until signalled.
Definition: os0event.h:104
struct os_event * os_event_t
Definition: os0event.h:42
int64_t os_event_reset(os_event_t event)
Resets an event semaphore to the non-signaled state.
Definition: os0event.cc:568
Inlined implementation for os_event_*.
required string event
Definition: replication_group_member_actions.proto:32
InnoDB condition variable.
Definition: os0event.cc:63
Version control for database, common definitions, and include files.
unsigned long int ulint
Definition: univ.i:406