1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
/*
Trivial FD monitoring
Copyright (C) Martin Schwenke & Amitay Isaacs, DataDirect Networks 2022
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __CTDB_TMON_H__
#define __CTDB_TMON_H__
#include <talloc.h>
#include <tevent.h>
/**
* @file tmon.h
*
* @brief Interprocess file descriptor (pipe and socketpair) monitoring
*
* Assumes 2 processes connected by a pipe(2) or a socketpair(2). A
* simple protocol is defined to allow sending various types of status
* information. When a pipe(2) is used the reader can monitor for
* close and read packets, while the sender can write packets. When a
* socketpair(2) is used then both ends can monitor for close, and
* read and write packets. A read timeout can be specified,
* terminating the computation if no packets are received.
*
* A simplified interface is provided to monitor for close and allow
* sending/monitoring of one-way ping packets. A ping timeout occurs
* when one end is expecting pings but none are received during the
* timeout interval - no response is sent to pings, they merely reset
* a timer on the receiving end.
*/
struct tmon_pkt;
struct tmon_actions {
int (*write_callback)(void *private_data, struct tmon_pkt *pkt);
int (*timeout_callback)(void *private_data);
int (*read_callback)(void *private_data, struct tmon_pkt *pkt);
int (*close_callback)(void *private_data);
};
/*
* Return value from write_callback() and read_callback() to cause the
* computation to exit successfully. For consistency this can also be
* used with timeout_callback() and close_callback().
*/
#define TMON_STATUS_EXIT (-1)
/* Return value from write_callback() to skip write */
#define TMON_STATUS_SKIP (-2)
/* For direction, below */
#define TMON_FD_READ 0x1
#define TMON_FD_WRITE 0x2
#define TMON_FD_BOTH (TMON_FD_READ | TMON_FD_WRITE)
/**
* @brief Async computation to start FD monitoring
*
* @param[in] mem_ctx Talloc memory context
* @param[in] ev Tevent context
* @param[in] fd File descriptor for "this" end of pipe/socketpair
* @param[in] direction Read, write or both - for sanity checking
* @param[in] read_timeout Seconds to trigger timeout when no packets received
* @param[in] write_interval Seconds to trigger write_callback
* @param[in] actions struct containing callbacks
* @param[in] private_data Passed to callbacks
* @return new tevent request or NULL on failure
*
* @note read_timeout implies monitor_close
*
* @note The computation will complete when:
*
* - The writing end closes (e.g. writer process terminates) - EPIPE
* - read_timeout is non-zero and timeout occurs - ETIMEDOUT
* - Packets received with no read_callback defined - EIO
* - Invalid or unexpected packet received - EPROTO
* - File descriptor readable but no bytes to read - error: EPIPE
* - Invalid combination of direction, callbacks, timeouts: EINVAL
* - An unexpected error occurs - other
*
* @note action callbacks return an int that can be used to trigger
* other errors or override an error. For example:
*
* - write_callback() can return non-zero errno, causing an error
* - close_callback() can return zero, overriding the default EPIPE error
* - timeout_callback() can return something other than ETIMEDOUT
* - read_callback() can return EPROTO for unexpected packet types
*
* Reading of exit and errno packets is handled internally (read
* callback is never called). Write callback can return special
* value TMON_STATUS_SKIP to avoid sending any data.
*/
struct tevent_req *tmon_send(TALLOC_CTX *mem_ctx,
struct tevent_context *ev,
int fd,
int direction,
unsigned long read_timeout,
unsigned long write_interval,
struct tmon_actions *actions,
void *private_data);
/**
* @brief Async computation to end FD monitoring
*
* @param[in] req Tevent request
* @param[out] perr errno in case of failure
* @return true on success, false on failure
*/
bool tmon_recv(struct tevent_req *req, int *perr);
/**
* @brief Fill in an exit packet
*
* @param[in,out] pkt An exit packet
* @return true on success, false on failure
*/
bool tmon_set_exit(struct tmon_pkt *pkt);
/**
* @brief Fill in an errno packet
*
* @param[in,out] pkt An errno packet
* @param[in] err An errno to send in packet
* @return true on success, false on failure
*/
bool tmon_set_errno(struct tmon_pkt *pkt, int err);
/**
* @brief Fill in a ping packet
*
* @param[in,out] pkt A ping packet
* @return true on success, false on failure
*/
bool tmon_set_ping(struct tmon_pkt *pkt);
/**
* @brief Fill in an ASCII packet
*
* @param[in,out] pkt An ASCII packet
* @param[in] c An ASCII character to send in packet
* @return true on success, false on failure
*/
bool tmon_set_ascii(struct tmon_pkt *pkt, char c);
/**
* @brief Fill in a custom packet
*
* @param[in,out] pkt A custom packet
* @param[in] val A uint16_t to send in a custom packet
* @return true on success, false on failure
*/
bool tmon_set_custom(struct tmon_pkt *pkt, uint16_t val);
/**
* @brief Validate a ping packet
*
* @param[in] pkt A ping packet
* @return true on success, false on failure
*/
bool tmon_parse_ping(struct tmon_pkt *pkt);
/**
* @brief Validate ASCII packet and parse out character
*
* @param[in] pkt An ASCII packet
* @param[out] c An ASCII character value from packet
* @return true on success, false on failure
*/
bool tmon_parse_ascii(struct tmon_pkt *pkt, char *c);
/**
* @brief Validate custom packet and parse out value
*
* @param[in] pkt A custom packet
* @param[out] val A uint16_t value from packet
* @return true on success, false on failure
*/
bool tmon_parse_custom(struct tmon_pkt *pkt, uint16_t *val);
/**
* @brief Write a packet
*
* @param[in] req Tevent request created by tmon_send
* @param[in] pkt Packet to write
* @return true on success, false on failure
*/
bool tmon_write(struct tevent_req *req, struct tmon_pkt *pkt);
/**
* @brief Async computation to start ping monitoring
*
* @param[in] mem_ctx Talloc memory context
* @param[in] ev Tevent context
* @param[in] fd File descriptor for "this" end of pipe/socketpair
* @param[in] direction Read, write or both - for sanity checking
* @param[in] timeout Timeout for pings on receiving end
* @param[in] interval Send a ping packet every interval seconds
*/
struct tevent_req *tmon_ping_send(TALLOC_CTX *mem_ctx,
struct tevent_context *ev,
int fd,
int direction,
unsigned long timeout,
unsigned long interval);
bool tmon_ping_recv(struct tevent_req *req, int *perr);
#endif /* __CTDB_TMON_H__ */
|
