Asterisk - The Open Source Telephony Project  21.4.1
alertpipe.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2017, Sean Bright
5  *
6  * Sean Bright <sean.bright@gmail.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 #ifndef ASTERISK_ALERTPIPE_H
20 #define ASTERISK_ALERTPIPE_H
21 
22 #include "asterisk/utils.h"
23 
24 typedef enum {
25  AST_ALERT_READ_SUCCESS = 0,
26  AST_ALERT_NOT_READABLE,
27  AST_ALERT_READ_FAIL,
28  AST_ALERT_READ_FATAL,
29 } ast_alert_status_t;
30 
31 /*!
32  * \brief Initialize an alert pipe
33  * \since 13.16.0
34  *
35  * \param alert_pipe a two-element array to hold the alert pipe's file descriptors
36  *
37  * \retval non-zero if a failure occurred.
38  * \retval zero otherwise.
39  */
40 int ast_alertpipe_init(int alert_pipe[2]);
41 
42 /*!
43  * \brief Close an alert pipe
44  * \since 13.16.0
45  *
46  * \param alert_pipe a two-element containing the alert pipe's file descriptors
47  */
48 void ast_alertpipe_close(int alert_pipe[2]);
49 
50 /*!
51  * \brief Read an event from an alert pipe
52  * \since 13.16.0
53  *
54  * \param alert_pipe a two-element array containing the alert pipe's file descriptors
55  *
56  * \retval AST_ALERT_READ_SUCCESS on success
57  * \retval AST_ALERT_NOT_READABLE if the alert pipe is not readable
58  * \retval AST_ALERT_READ_FATAL if the alert pipe's file descriptors are in
59  * blocking mode, or a read error occurs.
60  */
61 ast_alert_status_t ast_alertpipe_read(int alert_pipe[2]);
62 
63 /*!
64  * \brief Write an event to an alert pipe
65  * \since 13.16.0
66  *
67  * \param alert_pipe a two-element array containing the alert pipe's file descriptors
68  *
69  * \retval 0 Success
70  * \retval 1 Failure
71  */
72 ssize_t ast_alertpipe_write(int alert_pipe[2]);
73 
74 /*!
75  * \brief Consume all alerts written to the alert pipe
76  * \since 13.16.0
77  *
78  * \param alert_pipe a two-element array containing the alert pipe's file descriptors
79  *
80  * \retval AST_ALERT_READ_SUCCESS on success
81  * \retval AST_ALERT_NOT_READABLE if the alert pipe is not readable
82  * \retval AST_ALERT_READ_FATAL if the alert pipe's file descriptors are in
83  * blocking mode, or a read error occurs.
84  */
85 ast_alert_status_t ast_alertpipe_flush(int alert_pipe[2]);
86 
87 /*!
88  * \brief Sets the alert pipe file descriptors to default values
89  * \since 13.16.0
90  *
91  * \param alert_pipe a two-element array containing the alert pipe's file descriptors
92  */
93 AST_INLINE_API(
94 void ast_alertpipe_clear(int alert_pipe[2]),
95 {
96  alert_pipe[0] = alert_pipe[1] = -1;
97 }
98 )
99 
100 /*!
101  * \brief Determine if the alert pipe is readable
102  * \since 13.16.0
103  *
104  * \param alert_pipe a two-element array containing the alert pipe's file descriptors
105  *
106  * \retval non-zero if the alert pipe is readable.
107  * \retval zero otherwise.
108  */
109 AST_INLINE_API(
110 int attribute_pure ast_alertpipe_readable(int alert_pipe[2]),
111 {
112  return alert_pipe[0] > -1;
113 }
114 )
115 
116 /*!
117  * \brief Determine if the alert pipe is writable
118  * \since 13.16.0
119  *
120  * \param alert_pipe a two-element array containing the alert pipe's file descriptors
121  *
122  * \retval non-zero if the alert pipe is writable.
123  * \retval zero otherwise.
124  */
125 AST_INLINE_API(
126 int attribute_pure ast_alertpipe_writable(int alert_pipe[2]),
127 {
128  return alert_pipe[1] > -1;
129 }
130 )
131 
132 /*!
133  * \brief Get the alert pipe's read file descriptor
134  * \since 13.16.0
135  *
136  * \param alert_pipe a two-element array containing the alert pipe's file descriptors
137  *
138  * \retval -1 if the file descriptor is not initialized.
139  * \retval non-negative otherwise.
140  */
141 AST_INLINE_API(
142 int attribute_pure ast_alertpipe_readfd(int alert_pipe[2]),
143 {
144  return alert_pipe[0];
145 }
146 )
147 
148 /*!
149  * \brief Swap the file descriptors from two alert pipes
150  * \since 13.16.0
151  *
152  * \param alert_pipe_1 a two-element array containing an alert pipe's file descriptors
153  * \param alert_pipe_2 a two-element array containing an alert pipe's file descriptors
154  */
155 AST_INLINE_API(
156 void ast_alertpipe_swap(int alert_pipe_1[2], int alert_pipe_2[2]),
157 {
158  SWAP(alert_pipe_1[0], alert_pipe_2[0]);
159  SWAP(alert_pipe_1[1], alert_pipe_2[1]);
160 }
161 )
162 
163 #endif /* ASTERISK_ALERTPIPE_H */
void ast_alertpipe_close(int alert_pipe[2])
Close an alert pipe.
Definition: alertpipe.c:79
Utility functions.
ast_alert_status_t ast_alertpipe_read(int alert_pipe[2])
Read an event from an alert pipe.
Definition: alertpipe.c:102
int ast_alertpipe_init(int alert_pipe[2])
Initialize an alert pipe.
Definition: alertpipe.c:38
ast_alert_status_t ast_alertpipe_flush(int alert_pipe[2])
Consume all alerts written to the alert pipe.
Definition: alertpipe.c:134
ssize_t ast_alertpipe_write(int alert_pipe[2])
Write an event to an alert pipe.
Definition: alertpipe.c:120