1/*****************************************************************************
2Copyright (c) 1995, 2014, Oracle and/or its affiliates. All Rights Reserved.
3
4This program is free software; you can redistribute it and/or modify it under
5the terms of the GNU General Public License as published by the Free Software
6Foundation; version 2 of the License.
7
8This program is distributed in the hope that it will be useful, but WITHOUT
9ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
10FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
11
12You should have received a copy of the GNU General Public License along with
13this program; if not, write to the Free Software Foundation, Inc.,
1451 Franklin Street, Suite 500, Boston, MA 02110-1335 USA
15
16*****************************************************************************/
17
18/**************************************************//**
19@file include/os0event.h
20The interface to the operating system condition variables
21
22Created 2012-09-23 Sunny Bains (split from os0sync.h)
23*******************************************************/
24
25#ifndef os0event_h
26#define os0event_h
27
28#include "univ.i"
29
30// Forward declaration.
31struct os_event;
32typedef struct os_event* os_event_t;
33
34/** Denotes an infinite delay for os_event_wait_time() */
35#define OS_SYNC_INFINITE_TIME ULINT_UNDEFINED
36
37/** Return value of os_event_wait_time() when the time is exceeded */
38#define OS_SYNC_TIME_EXCEEDED 1
39
40/**
41Creates an event semaphore, i.e., a semaphore which may just have two states:
42signaled and nonsignaled. The created event is manual reset: it must be reset
43explicitly by calling os_event_reset().
44@return the event handle */
45os_event_t os_event_create(const char*);
46
47/**
48Sets an event semaphore to the signaled state: lets waiting threads
49proceed. */
50void
51os_event_set(
52/*=========*/
53 os_event_t event); /*!< in/out: event to set */
54
55/**
56Check if the event is set.
57@return true if set */
58bool
59os_event_is_set(
60/*============*/
61 const os_event_t event); /*!< in: event to set */
62
63/**
64Resets an event semaphore to the nonsignaled state. Waiting threads will
65stop to wait for the event.
66The return value should be passed to os_even_wait_low() if it is desired
67that this thread should not wait in case of an intervening call to
68os_event_set() between this os_event_reset() and the
69os_event_wait_low() call. See comments for os_event_wait_low(). */
70int64_t
71os_event_reset(
72/*===========*/
73 os_event_t event); /*!< in/out: event to reset */
74
75/**
76Frees an event object. */
77void
78os_event_destroy(
79/*=============*/
80 os_event_t& event); /*!< in/own: event to free */
81
82/**
83Waits for an event object until it is in the signaled state.
84
85Typically, if the event has been signalled after the os_event_reset()
86we'll return immediately because event->is_set == TRUE.
87There are, however, situations (e.g.: sync_array code) where we may
88lose this information. For example:
89
90thread A calls os_event_reset()
91thread B calls os_event_set() [event->is_set == TRUE]
92thread C calls os_event_reset() [event->is_set == FALSE]
93thread A calls os_event_wait() [infinite wait!]
94thread C calls os_event_wait() [infinite wait!]
95
96Where such a scenario is possible, to avoid infinite wait, the
97value returned by os_event_reset() should be passed in as
98reset_sig_count. */
99void
100os_event_wait_low(
101/*==============*/
102 os_event_t event, /*!< in/out: event to wait */
103 int64_t reset_sig_count);/*!< in: zero or the value
104 returned by previous call of
105 os_event_reset(). */
106
107/** Blocking infinite wait on an event, until signealled.
108@param e - event to wait on. */
109#define os_event_wait(e) os_event_wait_low((e), 0)
110
111/**
112Waits for an event object until it is in the signaled state or
113a timeout is exceeded. In Unix the timeout is always infinite.
114@return 0 if success, OS_SYNC_TIME_EXCEEDED if timeout was exceeded */
115ulint
116os_event_wait_time_low(
117/*===================*/
118 os_event_t event, /*!< in/out: event to wait */
119 ulint time_in_usec, /*!< in: timeout in
120 microseconds, or
121 OS_SYNC_INFINITE_TIME */
122 int64_t reset_sig_count); /*!< in: zero or the value
123 returned by previous call of
124 os_event_reset(). */
125
126/** Blocking timed wait on an event.
127@param e - event to wait on.
128@param t - timeout in microseconds */
129#define os_event_wait_time(e, t) os_event_wait_time_low((e), (t), 0)
130
131#endif /* !os0event_h */
132