4 Copyright (C) Amitay Isaacs 2015
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 3 of the License, or
9 (at your option) any later version.
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with this program; if not, see <http://www.gnu.org/licenses/>.
20 #ifndef __CTDB_CLIENT_H__
21 #define __CTDB_CLIENT_H__
26 #include "protocol/protocol.h"
27 #include "common/srvid.h"
32 * @brief Client api to talk to ctdb daemon
34 * This API allows one to connect to ctdb daemon, perform various database
35 * operations, send controls to ctdb daemon and send messages to other ctdb
40 * @brief The abstract context that holds client connection to ctdb daemon
42 struct ctdb_client_context
;
45 * @brief The abstract context that holds a tunnel endpoint
47 struct ctdb_tunnel_context
;
50 * @brief The abstract context that represents a clustered database
52 struct ctdb_db_context
;
55 * @brief The abstract context that represents a record from a distributed
58 struct ctdb_record_handle
;
61 * @brief The abstract context that represents a transaction on a replicated
64 struct ctdb_transaction_handle
;
67 * @brief Client callback function
69 * This function can be registered to be invoked in case of ctdb daemon going
72 typedef void (*ctdb_client_callback_func_t
)(void *private_data
);
75 * @brief Tunnel callback function
77 * This function is registered when a tunnel endpoint is set up. When the
78 * tunnel endpoint receives a message, this function is invoked.
80 typedef void (*ctdb_tunnel_callback_func_t
)(struct ctdb_tunnel_context
*tctx
,
81 uint32_t srcnode
, uint32_t reqid
,
82 uint8_t *buf
, size_t buflen
,
86 * @brief Async computation start to initialize a connection to ctdb daemon
88 * This returns a ctdb client context. Freeing this context will free the
89 * connection to ctdb daemon and any memory associated with it.
91 * If the connection to ctdb daemon is lost, the client will terminate
92 * automatically as the library will call exit(). If the client code
93 * wants to perform cleanup or wants to re-establish a new connection,
94 * the client should register a disconnect callback function.
96 * @see ctdb_client_set_disconnect_callback
98 * When a disconnect callback function is registered, client library will
99 * not call exit(). It is the responsibility of the client code to take
100 * appropriate action.
102 * @param[in] mem_ctx Talloc memory context
103 * @param[in] ev Tevent context
104 * @param[in] sockpath Path to ctdb daemon unix domain socket
105 * @return new tevent request, NULL on failure
107 struct tevent_req
*ctdb_client_init_send(TALLOC_CTX
*mem_ctx
,
108 struct tevent_context
*ev
,
109 const char *sockpath
);
112 * @brief Async computation end to initialize a connection to ctdb daemon
114 * @param[in] req Tevent request
115 * @param[out] perr errno in case of failure
116 * @param[in] mem_ctx Talloc memory context
117 * @param[out] result The new ctdb client context
118 * @return true on success, false on failure
120 bool ctdb_client_init_recv(struct tevent_req
*req
, int *perr
,
122 struct ctdb_client_context
**result
);
125 * @brief Sync wrapper to initialize ctdb connection
127 * @param[in] mem_ctx Talloc memory context
128 * @param[in] ev Tevent context
129 * @param[in] sockpath Path to ctdb daemon unix domain socket
130 * @param[out] result The new ctdb client context
131 * @return 0 on succcess, errno on failure
133 int ctdb_client_init(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
134 const char *sockpath
,
135 struct ctdb_client_context
**result
);
138 * @brief Register a callback in case of client disconnection
140 * This allows client code to know if the connection to ctdb daemon is lost.
141 * This is useful if the client wants to re-establish a new connection to ctdb
144 * @param[in] client Client connection context
145 * @param[in] func Callback function
146 * @param[in] private_data private data for callback function
148 void ctdb_client_set_disconnect_callback(struct ctdb_client_context
*client
,
149 ctdb_client_callback_func_t func
,
153 * @brief Get the node number of the current node
155 * @param[in] client Client connection context
156 * return node number on success, CTDB_UNKNOWN_PNN on error
158 uint32_t ctdb_client_pnn(struct ctdb_client_context
*client
);
161 * @brief Client event loop waiting for a flag
163 * This can used to wait for asynchronous computations to complete.
164 * When this function is called, it will run tevent event loop and wait
165 * till the done flag is set to true. This function will block and will
166 * not return as long as the done flag is false.
168 * @param[in] ev Tevent context
169 * @param[in] done Boolean flag to indicate when to stop waiting
171 void ctdb_client_wait(struct tevent_context
*ev
, bool *done
);
174 * @brief Client event loop waiting for function to return true with timeout
176 * This can be used to wait for asynchronous computations to complete.
177 * When this function is called, it will run tevent event loop and wait
178 * till the done function returns true or if the timeout occurs.
180 * This function will return when either
181 * - done function returns true, or
182 * - timeout has occurred.
184 * @param[in] ev Tevent context
185 * @param[in] done_func Function flag to indicate when to stop waiting
186 * @param[in] private_data Passed to done function
187 * @param[in] timeout How long to wait
188 * @return 0 on success, ETIMEDOUT on timeout, and errno on failure
190 int ctdb_client_wait_func_timeout(struct tevent_context
*ev
,
191 bool (*done_func
)(void *private_data
),
193 struct timeval timeout
);
196 * @brief Client event loop waiting for a flag with timeout
198 * This can be used to wait for asynchronous computations to complete.
199 * When this function is called, it will run tevent event loop and wait
200 * till the done flag is set to true or if the timeout occurs.
202 * This function will return when either
203 * - done flag is set to true, or
204 * - timeout has occurred.
206 * @param[in] ev Tevent context
207 * @param[in] done Boolean flag to indicate when to stop waiting
208 * @param[in] timeout How long to wait
209 * @return 0 on success, ETIMEDOUT on timeout, and errno on failure
211 int ctdb_client_wait_timeout(struct tevent_context
*ev
, bool *done
,
212 struct timeval timeout
);
215 * @brief Async computation start to wait till recovery is completed
217 * CTDB daemon does not perform many operations while in recovery (especially
218 * database operations). This computation allows one to wait till ctdb daemon has
221 * @param[in] mem_ctx Talloc memory context
222 * @param[in] ev Tevent context
223 * @param[in] client Client connection context
224 * @return new tevent request, or NULL on failure
226 struct tevent_req
*ctdb_recovery_wait_send(TALLOC_CTX
*mem_ctx
,
227 struct tevent_context
*ev
,
228 struct ctdb_client_context
*client
);
231 * @brief Async computation end to wait till recovery is completed
233 * @param[in] req Tevent request
234 * @param[out] perr errno in case of failure
235 * @return true on success, false on failure
237 bool ctdb_recovery_wait_recv(struct tevent_req
*req
, int *perr
);
240 * @brief Sync wrapper for ctdb_recovery_wait computation
242 * @param[in] ev Tevent context
243 * @param[in] client Client connection context
244 * @return true on success, false on failure
246 bool ctdb_recovery_wait(struct tevent_context
*ev
,
247 struct ctdb_client_context
*client
);
250 * @brief Async computation start to migrate a database record
252 * This sends a request to ctdb daemon to migrate a database record to
253 * the local node. CTDB daemon will locate the data master for the record
254 * and will migrate record (and the data master) to the current node.
256 * @see ctdb_fetch_lock_send
258 * @param[in] mem_ctx Talloc memory context
259 * @param[in] ev Tevent context
260 * @param[in] client Client connection context
261 * @param[in] request CTDB request data
262 * @return a new tevent req, or NULL on failure
264 struct tevent_req
*ctdb_client_call_send(TALLOC_CTX
*mem_ctx
,
265 struct tevent_context
*ev
,
266 struct ctdb_client_context
*client
,
267 struct ctdb_req_call
*request
);
270 * @brief Async computation end to migrate a database record
272 * @param[in] req Tevent request
273 * @param[in] mem_ctx Talloc memory context
274 * @param[out] reply CTDB reply data
275 * @param[out] perr errno in case of failure
276 * @return true on success, false on failure
278 bool ctdb_client_call_recv(struct tevent_req
*req
, TALLOC_CTX
*mem_ctx
,
279 struct ctdb_reply_call
**reply
, int *perr
);
283 * @brief Async computation start to send a message to remote client(s)
285 * This sends a message to ctdb clients on a remote node. All the
286 * messages are associated with a specific SRVID. All the clients on the
287 * remote node listening to that SRVID, will get the message.
289 * Clients can register and deregister for messages for a SRVID using
290 * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
292 * @see ctdb_client_set_message_handler_send,
293 * ctdb_client_remove_message_handler_send
295 * @param[in] mem_ctx Talloc memory context
296 * @param[in] ev Tevent context
297 * @param[in] client Client connection context
298 * @param[in] destnode Remote node id
299 * @param[in] message Message to send
300 * @return a new tevent req on success, NULL on failure
302 struct tevent_req
*ctdb_client_message_send(TALLOC_CTX
*mem_ctx
,
303 struct tevent_context
*ev
,
304 struct ctdb_client_context
*client
,
306 struct ctdb_req_message
*message
);
309 * @brief Async computation end to send a message to remote client(s)
311 * @param[in] req Tevent request
312 * @param[out] perr errno in case of failure
313 * @return true on success, false on failure
315 bool ctdb_client_message_recv(struct tevent_req
*req
, int *perr
);
318 * @brief Sync wrapper to send a message to client(s) on remote node
320 * @param[in] mem_ctx Talloc memory context
321 * @param[in] ev Tevent context
322 * @param[in] client Client connection context
323 * @param[in] destnode Node id
324 * @param[in] message Message to send
326 int ctdb_client_message(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
327 struct ctdb_client_context
*client
,
328 uint32_t destnode
, struct ctdb_req_message
*message
);
331 * @brief Async computation start to send a message to multiple nodes
333 * This sends a message to ctdb clients on multiple remote nodes. All the
334 * messages are associated with a specific SRVID. All the clients on remote
335 * nodes listening to that SRVID, will get the message.
337 * Clients can register and deregister for messages for a SRVID using
338 * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
340 * @see ctdb_client_set_message_handler_send,
341 * ctdb_client_remove_message_handler_send
343 * @param[in] mem_ctx Talloc memory context
344 * @param[in] ev Tevent context
345 * @param[in] client Client connection context
346 * @param[in] pnn_list List of node ids
347 * @param[in] count Number of node ids
348 * @param[in] message Message to send
349 * @return a new tevent req on success, NULL on failure
351 struct tevent_req
*ctdb_client_message_multi_send(
353 struct tevent_context
*ev
,
354 struct ctdb_client_context
*client
,
355 uint32_t *pnn_list
, int count
,
356 struct ctdb_req_message
*message
);
359 * @brief Async computation end to send a message to multiple nodes
361 * @param[in] req Tevent request
362 * @param[out] perr errno in case of failure
363 * @param[in] mem_ctx Talloc memory context
364 * @param[out] perr_list The status from each node id
365 * @return true on success, false on failure
367 * If perr_list is not NULL, then the status (0 on success, errno on failure)
368 * of sending message to each of the node in the specified node list. The
369 * perr_list is an array of the same size as of pnn_list.
371 bool ctdb_client_message_multi_recv(struct tevent_req
*req
, int *perr
,
372 TALLOC_CTX
*mem_ctx
, int **perr_list
);
375 * @brief Sync wrapper to send a message to multiple nodes
377 * @param[in] mem_ctx Talloc memory context
378 * @param[in] ev Tevent context
379 * @param[in] client Client connection context
380 * @param[in] pnn_list List of node ids
381 * @param[in] count Number of node ids
382 * @param[in] message Message to send
383 * @param[out] perr_list The status from each node id
384 * @return 0 on success, errno on failure
386 int ctdb_client_message_multi(TALLOC_CTX
*mem_ctx
,
387 struct tevent_context
*ev
,
388 struct ctdb_client_context
*client
,
389 uint32_t *pnn_list
, int count
,
390 struct ctdb_req_message
*message
,
394 * @brief Async computation start to receive messages for a SRVID
396 * This computation informs ctdb that the client is interested in all messages
397 * for a specific SRVID.
399 * @param[in] mem_ctx Talloc memory context
400 * @param[in] ev Tevent context
401 * @param[in] client Client connection context
402 * @param[in] srvid SRVID
403 * @param[in] handler Callback function to call when a message is received
404 * @param[in] private_data Private data for callback
405 * @return a new tevent req on success, NULL on failure
407 struct tevent_req
*ctdb_client_set_message_handler_send(
409 struct tevent_context
*ev
,
410 struct ctdb_client_context
*client
,
412 srvid_handler_fn handler
,
416 * @brief Async computation end to receive messages for a SRVID
418 * @param[in] req Tevent request
419 * @param[out] perr errno in case of failure
420 * @return true on success, false on failure
422 bool ctdb_client_set_message_handler_recv(struct tevent_req
*req
, int *perr
);
425 * Sync wrapper to receive messages for a SRVID
427 * @param[in] ev Tevent context
428 * @param[in] client Client connection context
429 * @param[in] srvid SRVID
430 * @param[in] handler Callback function to call when a message is received
431 * @param[in] private_data Private data for callback
432 * @return 0 on success, errno on failure
434 int ctdb_client_set_message_handler(struct tevent_context
*ev
,
435 struct ctdb_client_context
*client
,
436 uint64_t srvid
, srvid_handler_fn handler
,
440 * @brief Async computation start to stop receiving messages for a SRVID
442 * This computation informs ctdb that the client is no longer interested in
443 * messages for a specific SRVID.
445 * @param[in] mem_ctx Talloc memory context
446 * @param[in] ev Tevent context
447 * @param[in] client Client connection context
448 * @param[in] srvid SRVID
449 * @param[in] private_data Private data used to register callback
450 * @return a new tevent req on success, NULL on failure
452 struct tevent_req
*ctdb_client_remove_message_handler_send(
454 struct tevent_context
*ev
,
455 struct ctdb_client_context
*client
,
460 * @brief Async computation end to stop receiving messages for a SRVID
462 * @param[in] req Tevent request
463 * @param[out] perr errno in case of failure
464 * @return true on success, false on failure
466 bool ctdb_client_remove_message_handler_recv(struct tevent_req
*req
,
470 * Sync wrapper to stop receiving messages for a SRVID
472 * @param[in] ev Tevent context
473 * @param[in] client Client connection context
474 * @param[in] srvid SRVID
475 * @param[in] private_data Private data used to register callback
476 * @return 0 on success, errno on failure
478 int ctdb_client_remove_message_handler(struct tevent_context
*ev
,
479 struct ctdb_client_context
*client
,
480 uint64_t srvid
, void *private_data
);
483 * @brief Async computation start to send a control to ctdb daemon
485 * @param[in] mem_ctx Talloc memory context
486 * @param[in] ev Tevent context
487 * @param[in] client Client connection context
488 * @param[in] destnode Node id
489 * @param[in] timeout How long to wait
490 * @param[in] request Control request
491 * @return a new tevent req on success, NULL on failure
493 struct tevent_req
*ctdb_client_control_send(TALLOC_CTX
*mem_ctx
,
494 struct tevent_context
*ev
,
495 struct ctdb_client_context
*client
,
497 struct timeval timeout
,
498 struct ctdb_req_control
*request
);
501 * @brief Async computation end to send a control to ctdb daemon
503 * @param[in] req Tevent request
504 * @param[out] perr errno in case of failure
505 * @param[in] mem_ctx Talloc memory context
506 * @param[out] preply Control reply
507 * @return true on success, false on failure
509 bool ctdb_client_control_recv(struct tevent_req
*req
, int *perr
,
511 struct ctdb_reply_control
**preply
);
514 * @brief Sync wrapper to send a control to ctdb daemon
516 * @param[in] mem_ctx Talloc memory context
517 * @param[in] ev Tevent context
518 * @param[in] client Client connection context
519 * @param[in] destnode Node id
520 * @param[in] timeout How long to wait
521 * @param[in] request Control request
522 * @param[out] preply Control reply
523 * @return 0 on success, errno on failure
525 int ctdb_client_control(TALLOC_CTX
*mem_ctx
,
526 struct tevent_context
*ev
,
527 struct ctdb_client_context
*client
,
529 struct timeval timeout
,
530 struct ctdb_req_control
*request
,
531 struct ctdb_reply_control
**preply
);
534 * @brief Async computation start to send a control to multiple nodes
536 * @param[in] mem_ctx Talloc memory context
537 * @param[in] ev Tevent context
538 * @param[in] client Client connection context
539 * @param[in] pnn_list List of node ids
540 * @param[in] count Number of node ids
541 * @param[in] timeout How long to wait
542 * @param[in] request Control request
543 * @return a new tevent req on success, NULL on failure
545 struct tevent_req
*ctdb_client_control_multi_send(
547 struct tevent_context
*ev
,
548 struct ctdb_client_context
*client
,
549 uint32_t *pnn_list
, int count
,
550 struct timeval timeout
,
551 struct ctdb_req_control
*request
);
554 * @brief Async computation end to send a control to multiple nodes
556 * @param[in] req Tevent request
557 * @param[out] perr errno in case of failure
558 * @param[in] mem_ctx Talloc memory context
559 * @param[out] perr_list Status from each node
560 * @param[out] preply Control reply from each node
561 * @return true on success, false on failure
563 bool ctdb_client_control_multi_recv(struct tevent_req
*req
, int *perr
,
564 TALLOC_CTX
*mem_ctx
, int **perr_list
,
565 struct ctdb_reply_control
***preply
);
568 * @brief Sync wrapper to send a control to multiple nodes
570 * @param[in] mem_ctx Talloc memory context
571 * @param[in] ev Tevent context
572 * @param[in] client Client connection context
573 * @param[in] pnn_list List of node ids
574 * @param[in] count Number of node ids
575 * @param[in] timeout How long to wait
576 * @param[in] request Control request
577 * @param[out] perr_list Status from each node
578 * @param[out] preply Control reply from each node
579 * @return 0 on success, errno on failure
581 int ctdb_client_control_multi(TALLOC_CTX
*mem_ctx
,
582 struct tevent_context
*ev
,
583 struct ctdb_client_context
*client
,
584 uint32_t *pnn_list
, int count
,
585 struct timeval timeout
,
586 struct ctdb_req_control
*request
,
588 struct ctdb_reply_control
***preply
);
591 * @brief Check err_list for errors
593 * This is a convenience function to parse the err_list returned from
594 * functions that send requests to multiple nodes.
596 * If status from any of the node is non-zero, then return first non-zero
599 * If status from all the nodes is 0, then return 0.
601 * @param[in] pnn_list List of node ids
602 * @param[in] count Number of node ids
603 * @param[in] err_list Status from each node
604 * @param[out] pnn Node id in case of failure
605 * @return 0 if no failures, status from first failure
607 int ctdb_client_control_multi_error(uint32_t *pnn_list
, int count
,
608 int *err_list
, uint32_t *pnn
);
611 * @brief Async computation start to setup a tunnel endpoint
613 * This computation sets up a tunnel endpoint corresponding to a tunnel_id.
614 * A tunnel is a ctdb transport to deliver new protocol between endpoints.
616 * For two endpoints to communicate using new protocol,
617 * 1. Set up tunnel endpoints
620 * 4. Destroy tunnel endpoints
622 * @param[in] mem_ctx Talloc memory context
623 * @param[in] ev Tevent context
624 * @param[in] client Client connection context
625 * @param[in] tunnel_id Unique tunnel id
626 * @param[in] callback Callback function to call when a message is received
627 * @param[in] private_data Private data for callback
628 * @return a new tevent req on success, NULL on failure
630 struct tevent_req
*ctdb_tunnel_setup_send(TALLOC_CTX
*mem_ctx
,
631 struct tevent_context
*ev
,
632 struct ctdb_client_context
*client
,
634 ctdb_tunnel_callback_func_t callback
,
638 * @brief Async computation end to setup a tunnel
640 * @param[in] req Tevent request
641 * @param[in] perr errno in case of failure
642 * @param[out] result A new tunnel context
643 * @return true on success, false on failure
645 * Tunnel context should never be freed by user.
647 bool ctdb_tunnel_setup_recv(struct tevent_req
*req
, int *perr
,
648 struct ctdb_tunnel_context
**result
);
651 * @brief Sync wrapper for ctdb_tunnel_setup computation
653 * @param[in] mem_ctx Talloc memory context
654 * @param[in] ev Tevent context
655 * @param[in] client Client connection context
656 * @param[in] tunnel_id Unique tunnel id
657 * @param[in] callback Callback function to call when a message is received
658 * @param[in] private_data Private data for callback
659 * @param[out] result A new tunnel context
660 * @return 0 on success, errno on failure
662 int ctdb_tunnel_setup(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
663 struct ctdb_client_context
*client
, uint64_t tunnel_id
,
664 ctdb_tunnel_callback_func_t callback
, void *private_data
,
665 struct ctdb_tunnel_context
**result
);
668 * @brief Async computation start to destroy a tunnel endpoint
670 * This computation destroys the tunnel endpoint.
672 * @param[in] mem_ctx Talloc memory context
673 * @param[in] ev Tevent context
674 * @param[in] tctx Tunnel context
675 * @return a new tevent req on success, NULL on failure
677 struct tevent_req
*ctdb_tunnel_destroy_send(TALLOC_CTX
*mem_ctx
,
678 struct tevent_context
*ev
,
679 struct ctdb_tunnel_context
*tctx
);
682 * @brief Async computation end to destroy a tunnel endpoint
684 * @param[in] req Tevent request
685 * @param[out] perr errno in case of failure
686 * @return true on success, false on failure
688 bool ctdb_tunnel_destroy_recv(struct tevent_req
*req
, int *perr
);
691 * @brief Sync wrapper for ctdb_tunnel_destroy computation
693 * @param[in] ev Tevent context
694 * @param[in] tctx Tunnel context
695 * @return 0 on success, errno on failure
697 int ctdb_tunnel_destroy(struct tevent_context
*ev
,
698 struct ctdb_tunnel_context
*tctx
);
701 * @brief Async computation start to send a request via a tunnel
703 * @param[in] mem_ctx Talloc memory context
704 * @param[in] ev Tevent context
705 * @param[in] tctx Tunnel context
706 * @param[in] destnode PNN of destination
707 * @param[in] timeout How long to wait
708 * @param[in] buf Message to send
709 * @param[in] buflen Size of the message to send
710 * @param[in] wait_for_reply Whether to wait for reply
711 * @return a new tevent req on success, NULL on failure
713 struct tevent_req
*ctdb_tunnel_request_send(TALLOC_CTX
*mem_ctx
,
714 struct tevent_context
*ev
,
715 struct ctdb_tunnel_context
*tctx
,
717 struct timeval timeout
,
718 uint8_t *buf
, size_t buflen
,
719 bool wait_for_reply
);
722 * @brief Async computation end to send a request via a tunnel
724 * @param[in] req Tevent request
725 * @param[out] perr errno in case of failure
726 * @param[in] mem_ctx Talloc context
727 * @param[out] buf Reply data if expected
728 * @param[out] buflen Size of reply data if expected
729 * @return true on success, false on failure
731 bool ctdb_tunnel_request_recv(struct tevent_req
*req
, int *perr
,
732 TALLOC_CTX
*mem_ctx
, uint8_t **buf
,
736 * @brief Sync wrapper for ctdb_tunnel_request computation
738 * @param[in] mem_ctx Talloc memory context
739 * @param[in] ev Tevent context
740 * @param[in] tctx Tunnel context
741 * @param[in] destnode PNN of destination
742 * @param[in] timeout How long to wait
743 * @param[in] buf Message to send
744 * @param[in] buflen Size of the message to send
745 * @param[in] wait_for_reply Whether to wait for reply
746 * @return 0 on success, errno on failure
748 int ctdb_tunnel_request(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
749 struct ctdb_tunnel_context
*tctx
, uint32_t destnode
,
750 struct timeval timeout
, uint8_t *buf
, size_t buflen
,
751 bool wait_for_reply
);
754 * @brief Async computation start to send a reply via a tunnel
756 * @param[in] mem_ctx Talloc memory context
757 * @param[in] ev Tevent context
758 * @param[in] tctx Tunnel context
759 * @param[in] destnode PNN of destination
760 * @param[in] reqid Request id
761 * @param[in] timeout How long to wait
762 * @param[in] buf Reply data
763 * @param[in] buflen Size of reply data
764 * @return a new tevent req on success, NULL on failure
766 struct tevent_req
*ctdb_tunnel_reply_send(TALLOC_CTX
*mem_ctx
,
767 struct tevent_context
*ev
,
768 struct ctdb_tunnel_context
*tctx
,
769 uint32_t destnode
, uint32_t reqid
,
770 struct timeval timeout
,
771 uint8_t *buf
, size_t buflen
);
774 * @brief Async computation end to send a reply via a tunnel
776 * @param[in] req Tevent request
777 * @param[out] perr errno in case of failure
778 * @return true on success, false on failure
780 bool ctdb_tunnel_reply_recv(struct tevent_req
*req
, int *perr
);
783 * @brief Sync wrapper for ctdb_tunnel_reply computation
785 * @param[in] mem_ctx Talloc memory context
786 * @param[in] ev Tevent context
787 * @param[in] tctx Tunnel context
788 * @param[in] destnode PNN of destination
789 * @param[in] reqid Request id
790 * @param[in] timeout How long to wait
791 * @param[in] buf Reply data
792 * @param[in] buflen Size of reply data
793 * @return 0 on success, errno on failure
795 int ctdb_tunnel_reply(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
796 struct ctdb_tunnel_context
*tctx
, uint32_t destnode
,
797 uint32_t reqid
, struct timeval timeout
,
798 uint8_t *buf
, size_t buflen
);
801 * @brief Async computation start to attach a database
803 * @param[in] mem_ctx Talloc memory context
804 * @param[in] ev Tevent context
805 * @param[in[ client Client connection context
806 * @param[in] timeout How long to wait
807 * @param[in] db_name Name of the database
808 * @param[in] db_flags Database flags
809 * @return a new tevent req on success, NULL on failure
811 struct tevent_req
*ctdb_attach_send(TALLOC_CTX
*mem_ctx
,
812 struct tevent_context
*ev
,
813 struct ctdb_client_context
*client
,
814 struct timeval timeout
,
815 const char *db_name
, uint8_t db_flags
);
818 * @brief Async computation end to attach a database
820 * @param[in] req Tevent request
821 * @param[out] perr errno in case of failure
822 * @param[out] result New database context
823 * @return true on success, false on failure
825 bool ctdb_attach_recv(struct tevent_req
*req
, int *perr
,
826 struct ctdb_db_context
**result
);
829 * @brief Sync wrapper to attach a database
831 * @param[in] ev Tevent context
832 * @param[in[ client Client connection context
833 * @param[in] timeout How long to wait
834 * @param[in] db_name Name of the database
835 * @param[in] db_flags Database flags
836 * @param[out] result New database context
837 * @return 0 on success, errno on failure
839 int ctdb_attach(struct tevent_context
*ev
,
840 struct ctdb_client_context
*client
,
841 struct timeval timeout
,
842 const char *db_name
, uint8_t db_flags
,
843 struct ctdb_db_context
**result
);
846 * @brief Async computation start to detach a database
848 * Only volatile databases can be detached at runtime.
850 * @param[in] mem_ctx Talloc memory context
851 * @param[in] ev Tevent context
852 * @param[in[ client Client connection context
853 * @param[in] timeout How long to wait
854 * @param[in] db_id Database id
855 * @return a new tevent req on success, NULL on failure
857 struct tevent_req
*ctdb_detach_send(TALLOC_CTX
*mem_ctx
,
858 struct tevent_context
*ev
,
859 struct ctdb_client_context
*client
,
860 struct timeval timeout
, uint32_t db_id
);
863 * @brief Async computation end to detach a database
865 * @param[in] req Tevent request
866 * @param[out] perr errno in case of failure
867 * @return true on success, false on failure
869 bool ctdb_detach_recv(struct tevent_req
*req
, int *perr
);
872 * @brief Sync wrapper to detach a database
874 * Only volatile databases can be detached at runtime.
876 * @param[in] ev Tevent context
877 * @param[in[ client Client connection context
878 * @param[in] timeout How long to wait
879 * @param[in] db_id Database id
880 * @return 0 on success, errno on failure
882 int ctdb_detach(struct tevent_context
*ev
,
883 struct ctdb_client_context
*client
,
884 struct timeval timeout
, uint32_t db_id
);
888 * @brief Get database id from database context
890 * @param[in] db Database context
891 * @return database id
893 uint32_t ctdb_db_id(struct ctdb_db_context
*db
);
896 * @brief Traverse a database locally on the node
898 * This function traverses a database locally on the node and for each record
899 * calls the parser function. If the parser function returns 1, the traverse
900 * will terminate. If parser function returns 0, the traverse will continue
901 * till all records in database are parsed.
903 * This is useful for replicated databases, since each node has exactly the
906 * @param[in] db Database context
907 * @param[in] readonly Is the traversal for reading or updating
908 * @param[in] extract_header Whether to extract ltdb header from record data
909 * @param[in] parser Record parsing function
910 * @param[in] private_data Private data for parser function
911 * @return 0 on success, non-zero return value from parser function
913 int ctdb_db_traverse_local(struct ctdb_db_context
*db
, bool readonly
,
915 ctdb_rec_parser_func_t parser
, void *private_data
);
918 * @brief Async computation start to a cluster-wide database traverse
920 * This function traverses a database on all the nodes and for each record
921 * calls the parser function. If the parser function returns 1, the traverse
922 * will terminate. If parser function returns 0, the traverse will continue
923 * till all records all on nodes are parsed.
925 * This is useful for distributed databases as the records are distributed
926 * among the cluster nodes.
928 * @param[in] mem_ctx Talloc memory context
929 * @param[in] ev Tevent context
930 * @param[in] client Client connection context
931 * @param[in] db Database context
932 * @param[in] destnode Node id
933 * @param[in] timeout How long to wait
934 * @param[in] parser Record parser function
935 * @param[in] private_data Private data for parser
936 * @return a new tevent req on success, NULL on failure
938 struct tevent_req
*ctdb_db_traverse_send(TALLOC_CTX
*mem_ctx
,
939 struct tevent_context
*ev
,
940 struct ctdb_client_context
*client
,
941 struct ctdb_db_context
*db
,
943 struct timeval timeout
,
944 ctdb_rec_parser_func_t parser
,
948 * @brief Async computation end to a cluster-wide database traverse
950 * @param[in] req Tevent request
951 * @param[out] perr errno in case of failure
952 * @return true on success, false on failure
954 bool ctdb_db_traverse_recv(struct tevent_req
*req
, int *perr
);
957 * @brief Sync wrapper for a cluster-wide database traverse
959 * @param[in] mem_ctx Talloc memory context
960 * @param[in] ev Tevent context
961 * @param[in] client Client connection context
962 * @param[in] db Database context
963 * @param[in] destnode Node id
964 * @param[in] timeout How long to wait
965 * @param[in] parser Record parser function
966 * @param[in] private_data Private data for parser
967 * @return 0 on success, errno on failure or non-zero status from parser
969 int ctdb_db_traverse(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
970 struct ctdb_client_context
*client
,
971 struct ctdb_db_context
*db
,
972 uint32_t destnode
, struct timeval timeout
,
973 ctdb_rec_parser_func_t parser
, void *private_data
);
976 * @brief Fetch a record from a local database
978 * This function is primarily for internal use.
979 * Clients should use ctdb_fetch_lock() instead.
981 * @param[in] db Database context
982 * @param[in] key Record key
983 * @param[out] header Record header
984 * @param[in] mem_ctx Talloc memory context
985 * @param[out] data Record data
987 int ctdb_ltdb_fetch(struct ctdb_db_context
*db
, TDB_DATA key
,
988 struct ctdb_ltdb_header
*header
,
989 TALLOC_CTX
*mem_ctx
, TDB_DATA
*data
);
992 * @brief Async computation start to fetch a locked record
994 * This function is used to fetch a record from a distributed database.
996 * If the record is already available on the local node, then lock the
997 * record and return the record handle.
999 * If the record is not available on the local node, send a CTDB request to
1000 * migrate the record. Once the record is migrated to the local node, lock
1001 * the record and return the record handle.
1003 * At the end of the computation, a record handle is returned which holds
1004 * the record lock. When the record handle is freed, the record is unlocked.
1006 * @param[in] mem_ctx Talloc memory context
1007 * @param[in] ev Tevent context
1008 * @param[in] client Client context
1009 * @param[in] db Database context
1010 * @param[in] key Record key
1011 * @param[in] readonly Whether to request readonly copy of the record
1012 * @return a new tevent req on success, NULL on failure
1014 struct tevent_req
*ctdb_fetch_lock_send(TALLOC_CTX
*mem_ctx
,
1015 struct tevent_context
*ev
,
1016 struct ctdb_client_context
*client
,
1017 struct ctdb_db_context
*db
,
1018 TDB_DATA key
, bool readonly
);
1021 * @brief Async computation end to fetch a locked record
1023 * @param[in] req Tevent request
1024 * @param[out] header Record header
1025 * @param[in] mem_ctx Talloc memory context
1026 * @param[out] data Record data
1027 * @param[out] perr errno in case of failure
1028 * @return a new record handle, NULL on failure
1030 struct ctdb_record_handle
*ctdb_fetch_lock_recv(struct tevent_req
*req
,
1031 struct ctdb_ltdb_header
*header
,
1032 TALLOC_CTX
*mem_ctx
,
1033 TDB_DATA
*data
, int *perr
);
1036 * @brief Sync wrapper to fetch a locked record
1038 * @see ctdb_fetch_lock_send
1040 * @param[in] mem_ctx Talloc memory context
1041 * @param[in] ev Tevent context
1042 * @param[in] client Client context
1043 * @param[in] db Database context
1044 * @param[in] key Record key
1045 * @param[in] readonly Whether to request readonly copy of the record
1046 * @param[out] header Record header
1047 * @param[out] data Record data
1048 * return 0 on success, errno on failure
1050 int ctdb_fetch_lock(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
1051 struct ctdb_client_context
*client
,
1052 struct ctdb_db_context
*db
, TDB_DATA key
, bool readonly
,
1053 struct ctdb_record_handle
**out
,
1054 struct ctdb_ltdb_header
*header
, TDB_DATA
*data
);
1057 * @brief Update a locked record
1059 * This function is used to update a record in a distributed database.
1061 * This function should NOT be used to store null data, instead use
1062 * ctdb_delete_record().
1064 * @param[in] h Record handle
1065 * @param[in] data New record data
1066 * @return 0 on success, errno on failure
1068 int ctdb_store_record(struct ctdb_record_handle
*h
, TDB_DATA data
);
1071 * @brief Async computation start to delete a locked record
1073 * This function is used to delete a record in a distributed database
1075 * @param[in] mem_ctx Talloc memory context
1076 * @param[in] ev Tevent context
1077 * @param[in] h Record handle
1078 * @return a new tevent req on success, NULL on failure
1080 struct tevent_req
*ctdb_delete_record_send(TALLOC_CTX
*mem_ctx
,
1081 struct tevent_context
*ev
,
1082 struct ctdb_record_handle
*h
);
1085 * @brief Async computation end to delete a locked record
1087 * @param[in] req Tevent request
1088 * @param[out] perr errno in case of failure
1089 * @return true on success, false on failure
1091 bool ctdb_delete_record_recv(struct tevent_req
*req
, int *perr
);
1094 * @brief Sync wrapper to delete a locked record
1096 * @see ctdb_delete_record_send
1098 * @param[in] h Record handle
1099 * @return 0 on success, errno on failure
1101 int ctdb_delete_record(struct ctdb_record_handle
*h
);
1104 * @brief Async computation start to get a global database lock
1106 * Functions related to global locks are primarily used internally for
1107 * implementing transaction api.
1109 * Clients should use transaction api directly.
1110 * @see ctdb_transaction_start_send
1112 * @param[in] mem_ctx Talloc memory context
1113 * @param[in] ev Tevent context
1114 * @param[in] client Client context
1115 * @param[in] db Database context for g_lock.tdb
1116 * @param[in] keyname Record key
1117 * @param[in] sid Server id
1118 * @param[in] readonly Lock type
1119 * @return a new tevent req on success, NULL on failure
1121 struct tevent_req
*ctdb_g_lock_lock_send(TALLOC_CTX
*mem_ctx
,
1122 struct tevent_context
*ev
,
1123 struct ctdb_client_context
*client
,
1124 struct ctdb_db_context
*db
,
1125 const char *keyname
,
1126 struct ctdb_server_id
*sid
,
1130 * @brief Async computation end to get a global database lock
1132 * @param[in] req Tevent request
1133 * @param[out] perr errno in case of failure
1134 * @return true on success, false on failure
1136 bool ctdb_g_lock_lock_recv(struct tevent_req
*req
, int *perr
);
1139 * @brief Async computation start to release a global database lock
1141 * @param[in] mem_ctx Talloc memory context
1142 * @param[in] ev Tevent context
1143 * @param[in] client Client connection context
1144 * @param[in] db Database context
1145 * @param[in] keyname Record key
1146 * @param[in] sid Server id
1147 * @return a new tevent req on success, NULL on failure
1149 struct tevent_req
*ctdb_g_lock_unlock_send(TALLOC_CTX
*mem_ctx
,
1150 struct tevent_context
*ev
,
1151 struct ctdb_client_context
*client
,
1152 struct ctdb_db_context
*db
,
1153 const char *keyname
,
1154 struct ctdb_server_id sid
);
1157 * @brief Async computation end to release a global database lock
1159 * @param[in] req Tevent request
1160 * @param[out] perr errno in case of failure
1161 * @return true on success, false on failure
1163 bool ctdb_g_lock_unlock_recv(struct tevent_req
*req
, int *perr
);
1166 * @brief Async computation start to start a transaction
1168 * This function is used to start a transaction on a replicated database.
1170 * To perform any updates on a replicated database
1171 * - start transaction
1172 * - fetch record (ctdb_transaction_fetch_record)
1173 * - store record (ctdb_transaction_store_record)
1174 * - delete record (ctdb_transaction_delete_record)
1175 * - commit transaction (ctdb_transaction_commit_send), or
1176 * - cancel transaction (ctdb_transaction_cancel_send)
1178 * Starting a transaction will return a transaction handle. This is used
1179 * for updating records under a transaction. This handle is automatically
1180 * freed once the transacion is committed or cancelled.
1182 * Clients should NOT free the transaction handle.
1184 * @param[in] mem_ctx Talloc memory context
1185 * @param[in] ev Tevent context
1186 * @param[in] client Client connection context
1187 * @param[in] timeout How long to wait
1188 * @param[in] db Database context
1189 * @param[in] readonly Is transaction readonly
1190 * @return a new tevent req on success, NULL on failure
1192 struct tevent_req
*ctdb_transaction_start_send(TALLOC_CTX
*mem_ctx
,
1193 struct tevent_context
*ev
,
1194 struct ctdb_client_context
*client
,
1195 struct timeval timeout
,
1196 struct ctdb_db_context
*db
,
1200 * @brief Async computation end to start a transaction
1202 * @param[in] req Tevent request
1203 * @param[out] perr errno in case of failure
1204 * @return a new transaction handle on success, NULL on failure
1206 struct ctdb_transaction_handle
*ctdb_transaction_start_recv(
1207 struct tevent_req
*req
,
1211 * @brief Sync wrapper to start a transaction
1213 * @see ctdb_transaction_start_send
1215 * @param[in] mem_ctx Talloc memory context
1216 * @param[in] ev Tevent context
1217 * @param[in] client Client connection context
1218 * @param[in] timeout How long to wait
1219 * @param[in] db Database context
1220 * @param[in] readonly Is transaction readonly
1221 * @param[out] result a new transaction handle
1222 * @return 0 on success, errno on failure
1224 int ctdb_transaction_start(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
1225 struct ctdb_client_context
*client
,
1226 struct timeval timeout
,
1227 struct ctdb_db_context
*db
, bool readonly
,
1228 struct ctdb_transaction_handle
**result
);
1231 * @brief Fetch a record under a transaction
1233 * @see ctdb_transaction_start_send
1235 * @param[in] h Transaction handle
1236 * @param[in] key Record key
1237 * @param[in] mem_ctx Talloc memory context
1238 * @param[out] data Record data
1239 * @return 0 on success, errno on failure
1241 int ctdb_transaction_fetch_record(struct ctdb_transaction_handle
*h
,
1243 TALLOC_CTX
*mem_ctx
, TDB_DATA
*data
);
1246 * @brief Store a record under a transaction
1248 * @see ctdb_transaction_start_send
1250 * @param[in] h Transaction handle
1251 * @param[in] key Record key
1252 * @param[in] data New record data
1253 * @return 0 on success, errno on failure
1255 int ctdb_transaction_store_record(struct ctdb_transaction_handle
*h
,
1256 TDB_DATA key
, TDB_DATA data
);
1259 * @brief Delete a record under a transaction
1261 * @see ctdb_transaction_start_send
1263 * @param[in] h Transaction handle
1264 * @param[in] key Record key
1265 * @return 0 on success, errno on failure
1267 int ctdb_transaction_delete_record(struct ctdb_transaction_handle
*h
,
1271 * @brief Async computation start to commit a transaction
1273 * @see ctdb_transaction_start_send
1275 * @param[in] mem_ctx Talloc memory context
1276 * @param[in] ev Tevent context
1277 * @param[in] timeout How long to wait
1278 * @param[in] h Transaction handle
1279 * @return a new tevent req on success, NULL on failure
1281 struct tevent_req
*ctdb_transaction_commit_send(
1282 TALLOC_CTX
*mem_ctx
,
1283 struct tevent_context
*ev
,
1284 struct timeval timeout
,
1285 struct ctdb_transaction_handle
*h
);
1288 * @brief Async computation end to commit a transaction
1290 * @param[in] req Tevent request
1291 * @param[out] perr errno in case of failure
1292 * @return true on success, false on failure
1294 bool ctdb_transaction_commit_recv(struct tevent_req
*req
, int *perr
);
1297 * @brief Sync wrapper to commit a transaction
1299 * @see ctdb_transaction_commit_send
1301 * @param[in] h Transaction handle
1302 * @return 0 on success, errno on failure
1304 int ctdb_transaction_commit(struct ctdb_transaction_handle
*h
);
1307 * @brief Async computation start to cancel a transaction
1309 * @see ctdb_transaction_start_send
1311 * @param[in] mem_ctx Talloc memory context
1312 * @param[in] ev Tevent context
1313 * @param[in] timeout How long to wait
1314 * @param[in] h Transaction handle
1315 * @return a new tevent req on success, NULL on failure
1317 struct tevent_req
*ctdb_transaction_cancel_send(
1318 TALLOC_CTX
*mem_ctx
,
1319 struct tevent_context
*ev
,
1320 struct timeval timeout
,
1321 struct ctdb_transaction_handle
*h
);
1324 * @brief Async computation end to cancel a transaction
1326 * @param[in] req Tevent request
1327 * @param[out] perr errno in case of failure
1328 * @return true on success, false on failure
1330 bool ctdb_transaction_cancel_recv(struct tevent_req
*req
, int *perr
);
1333 * @brief Sync wrapper to cancel a transaction
1335 * @see ctdb_transaction_cancel_send
1337 * @param[in] h Transaction handle
1338 * @return 0 on success, errno on failure
1340 int ctdb_transaction_cancel(struct ctdb_transaction_handle
*h
);
1343 * @brief Utility function to extract a list of node ids from nodemap
1345 * @param[in] nodemap Node map
1346 * @param[in] flags_mask Flags to match on
1347 * @param[in] exclude_pnn Node id to exclude from the list
1348 * @param[in] mem_ctx Talloc memory context
1349 * @param[out] pnn_list List of node ids
1350 * @return number of node ids on success, -1 on failure
1352 int list_of_nodes(struct ctdb_node_map
*nodemap
,
1353 uint32_t flags_mask
, uint32_t exclude_pnn
,
1354 TALLOC_CTX
*mem_ctx
, uint32_t **pnn_list
);
1357 * @brief Utility function to extract a list of node ids for active nodes
1359 * @param[in] nodemap Node map
1360 * @param[in] exclude_pnn Node id to exclude from the list
1361 * @param[in] mem_ctx Talloc memory context
1362 * @param[out] pnn_list List of node ids
1363 * @return number of node ids on success, -1 on failure
1365 int list_of_active_nodes(struct ctdb_node_map
*nodemap
, uint32_t exclude_pnn
,
1366 TALLOC_CTX
*mem_ctx
, uint32_t **pnn_list
);
1369 * @brief Utility function to extract a list of node ids for connected nodes
1371 * @param[in] nodemap Node map
1372 * @param[in] exclude_pnn Node id to exclude from the list
1373 * @param[in] mem_ctx Talloc memory context
1374 * @param[out] pnn_list List of node ids
1375 * @return number of node ids on success, -1 on failure
1377 int list_of_connected_nodes(struct ctdb_node_map
*nodemap
,
1378 uint32_t exclude_pnn
,
1379 TALLOC_CTX
*mem_ctx
, uint32_t **pnn_list
);
1382 * @brief Construct a new server id
1384 * @param[in] client Client connection context
1385 * @param[in] task_id Task id
1386 * @return a new server id
1388 struct ctdb_server_id
ctdb_client_get_server_id(
1389 struct ctdb_client_context
*client
,
1393 * @brief Check if two server ids are the same
1395 * @param[in] sid1 Server id 1
1396 * @param[in] sid2 Server id 2
1397 * @return true if the server ids are same, false otherwise
1399 bool ctdb_server_id_equal(struct ctdb_server_id
*sid1
,
1400 struct ctdb_server_id
*sid2
);
1403 * @brief Check if the process with server id exists
1405 * @param[in] mem_ctx Talloc memory context
1406 * @param[in] ev Tevent context
1407 * @param[in] client Client connection context
1408 * @param[in] sid Server id
1409 * @param[out] exists Boolean flag to indicate if the process exists
1410 * @return 0 on success, errno on failure
1412 int ctdb_server_id_exists(TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
,
1413 struct ctdb_client_context
*client
,
1414 struct ctdb_server_id
*sid
, bool *exists
);
1416 #endif /* __CTDB_CLIENT_H__ */