ctdb/client/client.h

   1 /*
   2    CTDB client code
   3
   4    Copyright (C) Amitay Isaacs  2015
   5
   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.
  10
  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.
  15
  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/>.
  18 */
  19
  20 #ifndef __CTDB_CLIENT_H__
  21 #define __CTDB_CLIENT_H__
  22
  23 #include <talloc.h>
  24 #include <tevent.h>
  25
  26 #include "protocol/protocol.h"
  27 #include "common/srvid.h"
  28
  29 /**
  30  * @file client.h
  31  *
  32  * @brief Client api to talk to ctdb daemon
  33  *
  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
  36  * clients.
  37  */
  38
  39 /**
  40  * @brief The abstract context that holds client connection to ctdb daemon
  41  */
  42 struct ctdb_client_context;
  43
  44 /**
  45  * @brief The abstract context that holds a tunnel endpoint
  46  */
  47 struct ctdb_tunnel_context;
  48
  49 /**
  50  * @brief The abstract context that represents a clustered database
  51  */
  52 struct ctdb_db_context;
  53
  54 /**
  55  * @brief The abstract context that represents a record from a distributed
  56  * database
  57  */
  58 struct ctdb_record_handle;
  59
  60 /**
  61  * @brief The abstract context that represents a transaction on a replicated
  62  * database
  63  */
  64 struct ctdb_transaction_handle;
  65
  66 /**
  67  * @brief Client callback function
  68  *
  69  * This function can be registered to be invoked in case of ctdb daemon going
  70  * away.
  71  */
  72 typedef void (*ctdb_client_callback_func_t)(void *private_data);
  73
  74 /**
  75  * @brief Tunnel callback function
  76  *
  77  * This function is registered when a tunnel endpoint is set up.  When the
  78  * tunnel endpoint receives a message, this function is invoked.
  79  */
  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,
  83                                             void *private_data);
  84
  85 /**
  86  * @brief Async computation start to initialize a connection to ctdb daemon
  87  *
  88  * This returns a ctdb client context.  Freeing this context will free the
  89  * connection to ctdb daemon and any memory associated with it.
  90  *
  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.
  95  *
  96  * @see ctdb_client_set_disconnect_callback
  97  *
  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.
 101  *
 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
 106  */
 107 struct tevent_req *ctdb_client_init_send(TALLOC_CTX *mem_ctx,
 108                                          struct tevent_context *ev,
 109                                          const char *sockpath);
 110
 111 /**
 112  * @brief Async computation end to initialize a connection to ctdb daemon
 113  *
 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
 119  */
 120 bool ctdb_client_init_recv(struct tevent_req *req, int *perr,
 121                            TALLOC_CTX *mem_ctx,
 122                            struct ctdb_client_context **result);
 123
 124 /**
 125  * @brief Sync wrapper to initialize ctdb connection
 126  *
 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 success, errno on failure
 132  */
 133 int ctdb_client_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 134                      const char *sockpath,
 135                      struct ctdb_client_context **result);
 136
 137 /**
 138  * @brief Register a callback in case of client disconnection
 139  *
 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
 142  * daemon.
 143  *
 144  * @param[in] client Client connection context
 145  * @param[in] func Callback function
 146  * @param[in] private_data private data for callback function
 147  */
 148 void ctdb_client_set_disconnect_callback(struct ctdb_client_context *client,
 149                                          ctdb_client_callback_func_t func,
 150                                          void *private_data);
 151
 152 /**
 153  * @brief Get the node number of the current node
 154  *
 155  * @param[in] client Client connection context
 156  * return node number on success, CTDB_UNKNOWN_PNN on error
 157  */
 158 uint32_t ctdb_client_pnn(struct ctdb_client_context *client);
 159
 160 /**
 161  * @brief Client event loop waiting for a flag
 162  *
 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.
 167  *
 168  * @param[in] ev Tevent context
 169  * @param[in] done Boolean flag to indicate when to stop waiting
 170  */
 171 void ctdb_client_wait(struct tevent_context *ev, bool *done);
 172
 173 /**
 174  * @brief Client event loop waiting for function to return true with timeout
 175  *
 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.
 179  *
 180  * This function will return when either
 181  *  - done function returns true, or
 182  *  - timeout has occurred.
 183  *
 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
 189  */
 190 int ctdb_client_wait_func_timeout(struct tevent_context *ev,
 191                                   bool (*done_func)(void *private_data),
 192                                   void *private_data,
 193                                   struct timeval timeout);
 194
 195 /**
 196  * @brief Client event loop waiting for a flag with timeout
 197  *
 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.
 201  *
 202  * This function will return when either
 203  *  - done flag is set to true, or
 204  *  - timeout has occurred.
 205  *
 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
 210  */
 211 int ctdb_client_wait_timeout(struct tevent_context *ev, bool *done,
 212                              struct timeval timeout);
 213
 214 /**
 215  * @brief Async computation start to wait till recovery is completed
 216  *
 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
 219  * finished recovery.
 220  *
 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
 225  */
 226 struct tevent_req *ctdb_recovery_wait_send(TALLOC_CTX *mem_ctx,
 227                                            struct tevent_context *ev,
 228                                            struct ctdb_client_context *client);
 229
 230 /**
 231  * @brief Async computation end to wait till recovery is completed
 232  *
 233  * @param[in] req Tevent request
 234  * @param[out] perr errno in case of failure
 235  * @return true on success, false on failure
 236  */
 237 bool ctdb_recovery_wait_recv(struct tevent_req *req, int *perr);
 238
 239 /**
 240  * @brief Sync wrapper for ctdb_recovery_wait computation
 241  *
 242  * @param[in] ev Tevent context
 243  * @param[in] client Client connection context
 244  * @return true on success, false on failure
 245  */
 246 bool ctdb_recovery_wait(struct tevent_context *ev,
 247                         struct ctdb_client_context *client);
 248
 249 /**
 250  * @brief Async computation start to migrate a database record
 251  *
 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.
 255  *
 256  * @see ctdb_fetch_lock_send
 257  *
 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
 263  */
 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);
 268
 269 /**
 270  * @brief Async computation end to migrate a database record
 271  *
 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
 277  */
 278 bool ctdb_client_call_recv(struct tevent_req *req, TALLOC_CTX *mem_ctx,
 279                            struct ctdb_reply_call **reply, int *perr);
 280
 281
 282 /**
 283  * @brief Async computation start to send a message to remote client(s)
 284  *
 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.
 288  *
 289  * Clients can register and deregister for messages for a SRVID using
 290  * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
 291  *
 292  * @see ctdb_client_set_message_handler_send,
 293  *      ctdb_client_remove_message_handler_send
 294  *
 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
 301  */
 302 struct tevent_req *ctdb_client_message_send(TALLOC_CTX *mem_ctx,
 303                                             struct tevent_context *ev,
 304                                             struct ctdb_client_context *client,
 305                                             uint32_t destnode,
 306                                             struct ctdb_req_message *message);
 307
 308 /**
 309  * @brief Async computation end to send a message to remote client(s)
 310  *
 311  * @param[in] req Tevent request
 312  * @param[out] perr errno in case of failure
 313  * @return true on success, false on failure
 314  */
 315 bool ctdb_client_message_recv(struct tevent_req *req, int *perr);
 316
 317 /**
 318  * @brief Sync wrapper to send a message to client(s) on remote node
 319  *
 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
 325  */
 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);
 329
 330 /**
 331  * @brief Async computation start to send a message to multiple nodes
 332  *
 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.
 336  *
 337  * Clients can register and deregister for messages for a SRVID using
 338  * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
 339  *
 340  * @see ctdb_client_set_message_handler_send,
 341  *      ctdb_client_remove_message_handler_send
 342  *
 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
 350  */
 351 struct tevent_req *ctdb_client_message_multi_send(
 352                                 TALLOC_CTX *mem_ctx,
 353                                 struct tevent_context *ev,
 354                                 struct ctdb_client_context *client,
 355                                 uint32_t *pnn_list, int count,
 356                                 struct ctdb_req_message *message);
 357
 358 /**
 359  * @brief Async computation end to send a message to multiple nodes
 360  *
 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
 366  *
 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.
 370  */
 371 bool ctdb_client_message_multi_recv(struct tevent_req *req, int *perr,
 372                                     TALLOC_CTX *mem_ctx, int **perr_list);
 373
 374 /**
 375  * @brief Sync wrapper to send a message to multiple nodes
 376  *
 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
 385  */
 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,
 391                               int **perr_list);
 392
 393 /**
 394  * @brief Async computation start to receive messages for a SRVID
 395  *
 396  * This computation informs ctdb that the client is interested in all messages
 397  * for a specific SRVID.
 398  *
 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
 406  */
 407 struct tevent_req *ctdb_client_set_message_handler_send(
 408                                         TALLOC_CTX *mem_ctx,
 409                                         struct tevent_context *ev,
 410                                         struct ctdb_client_context *client,
 411                                         uint64_t srvid,
 412                                         srvid_handler_fn handler,
 413                                         void *private_data);
 414
 415 /**
 416  * @brief Async computation end to receive messages for a SRVID
 417  *
 418  * @param[in] req Tevent request
 419  * @param[out] perr errno in case of failure
 420  * @return true on success, false on failure
 421  */
 422 bool ctdb_client_set_message_handler_recv(struct tevent_req *req, int *perr);
 423
 424 /**
 425  * Sync wrapper to receive messages for a SRVID
 426  *
 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
 433  */
 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,
 437                                     void *private_data);
 438
 439 /**
 440  * @brief Async computation start to stop receiving messages for a SRVID
 441  *
 442  * This computation informs ctdb that the client is no longer interested in
 443  * messages for a specific SRVID.
 444  *
 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
 451  */
 452 struct tevent_req *ctdb_client_remove_message_handler_send(
 453                                         TALLOC_CTX *mem_ctx,
 454                                         struct tevent_context *ev,
 455                                         struct ctdb_client_context *client,
 456                                         uint64_t srvid,
 457                                         void *private_data);
 458
 459 /**
 460  * @brief Async computation end to stop receiving messages for a SRVID
 461  *
 462  * @param[in] req Tevent request
 463  * @param[out] perr errno in case of failure
 464  * @return true on success, false on failure
 465  */
 466 bool ctdb_client_remove_message_handler_recv(struct tevent_req *req,
 467                                              int *perr);
 468
 469 /**
 470  * Sync wrapper to stop receiving messages for a SRVID
 471  *
 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
 477  */
 478 int ctdb_client_remove_message_handler(struct tevent_context *ev,
 479                                        struct ctdb_client_context *client,
 480                                        uint64_t srvid, void *private_data);
 481
 482 /**
 483  * @brief Async computation start to send a control to ctdb daemon
 484  *
 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
 492  */
 493 struct tevent_req *ctdb_client_control_send(TALLOC_CTX *mem_ctx,
 494                                             struct tevent_context *ev,
 495                                             struct ctdb_client_context *client,
 496                                             uint32_t destnode,
 497                                             struct timeval timeout,
 498                                             struct ctdb_req_control *request);
 499
 500 /**
 501  * @brief Async computation end to send a control to ctdb daemon
 502  *
 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
 508  */
 509 bool ctdb_client_control_recv(struct tevent_req *req, int *perr,
 510                               TALLOC_CTX *mem_ctx,
 511                               struct ctdb_reply_control **preply);
 512
 513 /**
 514  * @brief Sync wrapper to send a control to ctdb daemon
 515  *
 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
 524  */
 525 int ctdb_client_control(TALLOC_CTX *mem_ctx,
 526                         struct tevent_context *ev,
 527                         struct ctdb_client_context *client,
 528                         uint32_t destnode,
 529                         struct timeval timeout,
 530                         struct ctdb_req_control *request,
 531                         struct ctdb_reply_control **preply);
 532
 533 /**
 534  * @brief Async computation start to send a control to multiple nodes
 535  *
 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
 544  */
 545 struct tevent_req *ctdb_client_control_multi_send(
 546                                 TALLOC_CTX *mem_ctx,
 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);
 552
 553 /**
 554  * @brief Async computation end to send a control to multiple nodes
 555  *
 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
 562  */
 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);
 566
 567 /**
 568  * @brief Sync wrapper to send a control to multiple nodes
 569  *
 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
 580  */
 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,
 587                               int **perr_list,
 588                               struct ctdb_reply_control ***preply);
 589
 590 /**
 591  * @brief Check err_list for errors
 592  *
 593  * This is a convenience function to parse the err_list returned from
 594  * functions that send requests to multiple nodes.
 595  *
 596  * If status from any of the node is non-zero, then return first non-zero
 597  * status.
 598  *
 599  * If status from all the nodes is 0, then return 0.
 600  *
 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
 606  */
 607 int ctdb_client_control_multi_error(uint32_t *pnn_list, int count,
 608                                     int *err_list, uint32_t *pnn);
 609
 610 /**
 611  * @brief Async computation start to setup a tunnel endpoint
 612  *
 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.
 615  *
 616  * For two endpoints to communicate using new protocol,
 617  * 1. Set up tunnel endpoints
 618  * 2. Send requests
 619  * 3. Send replies
 620  * 4. Destroy tunnel endpoints
 621  *
 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
 629  */
 630 struct tevent_req *ctdb_tunnel_setup_send(TALLOC_CTX *mem_ctx,
 631                                           struct tevent_context *ev,
 632                                           struct ctdb_client_context *client,
 633                                           uint64_t tunnel_id,
 634                                           ctdb_tunnel_callback_func_t callback,
 635                                           void *private_data);
 636
 637 /**
 638  * @brief Async computation end to setup a tunnel
 639  *
 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
 644  *
 645  * Tunnel context should never be freed by user.
 646  */
 647 bool ctdb_tunnel_setup_recv(struct tevent_req *req, int *perr,
 648                             struct ctdb_tunnel_context **result);
 649
 650 /**
 651  * @brief Sync wrapper for ctdb_tunnel_setup computation
 652  *
 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
 661  */
 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);
 666
 667 /**
 668  * @brief Async computation start to destroy a tunnel endpoint
 669  *
 670  * This computation destroys the tunnel endpoint.
 671  *
 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
 676  */
 677 struct tevent_req *ctdb_tunnel_destroy_send(TALLOC_CTX *mem_ctx,
 678                                             struct tevent_context *ev,
 679                                             struct ctdb_tunnel_context *tctx);
 680
 681 /**
 682  * @brief Async computation end to destroy a tunnel endpoint
 683  *
 684  * @param[in] req Tevent request
 685  * @param[out] perr errno in case of failure
 686  * @return true on success, false on failure
 687  */
 688 bool ctdb_tunnel_destroy_recv(struct tevent_req *req, int *perr);
 689
 690 /**
 691  * @brief Sync wrapper for ctdb_tunnel_destroy computation
 692  *
 693  * @param[in] ev Tevent context
 694  * @param[in] tctx Tunnel context
 695  * @return 0 on success, errno on failure
 696  */
 697 int ctdb_tunnel_destroy(struct tevent_context *ev,
 698                         struct ctdb_tunnel_context *tctx);
 699
 700 /**
 701  * @brief Async computation start to send a request via a tunnel
 702  *
 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
 712  */
 713 struct tevent_req *ctdb_tunnel_request_send(TALLOC_CTX *mem_ctx,
 714                                             struct tevent_context *ev,
 715                                             struct ctdb_tunnel_context *tctx,
 716                                             uint32_t destnode,
 717                                             struct timeval timeout,
 718                                             uint8_t *buf, size_t buflen,
 719                                             bool wait_for_reply);
 720
 721 /**
 722  * @brief Async computation end to send a request via a tunnel
 723  *
 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
 730  */
 731 bool ctdb_tunnel_request_recv(struct tevent_req *req, int *perr,
 732                               TALLOC_CTX *mem_ctx, uint8_t **buf,
 733                               size_t *buflen);
 734
 735 /**
 736  * @brief Sync wrapper for ctdb_tunnel_request computation
 737  *
 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
 747  */
 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);
 752
 753 /**
 754  * @brief Async computation start to send a reply via a tunnel
 755  *
 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
 765  */
 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);
 772
 773 /**
 774  * @brief Async computation end to send a reply via a tunnel
 775  *
 776  * @param[in] req Tevent request
 777  * @param[out] perr errno in case of failure
 778  * @return true on success, false on failure
 779  */
 780 bool ctdb_tunnel_reply_recv(struct tevent_req *req, int *perr);
 781
 782 /**
 783  * @brief Sync wrapper for ctdb_tunnel_reply computation
 784  *
 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
 794  */
 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);
 799
 800 /**
 801  * @brief Async computation start to attach a database
 802  *
 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
 810  */
 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);
 816
 817 /**
 818  * @brief Async computation end to attach a database
 819  *
 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
 824  */
 825 bool ctdb_attach_recv(struct tevent_req *req, int *perr,
 826                       struct ctdb_db_context **result);
 827
 828 /**
 829  * @brief Sync wrapper to attach a database
 830  *
 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
 838  */
 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);
 844
 845 /**
 846  * @brief Async computation start to detach a database
 847  *
 848  * Only volatile databases can be detached at runtime.
 849  *
 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
 856  */
 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);
 861
 862 /**
 863  * @brief Async computation end to detach a database
 864  *
 865  * @param[in] req Tevent request
 866  * @param[out] perr errno in case of failure
 867  * @return true on success, false on failure
 868  */
 869 bool ctdb_detach_recv(struct tevent_req *req, int *perr);
 870
 871 /**
 872  * @brief Sync wrapper to detach a database
 873  *
 874  * Only volatile databases can be detached at runtime.
 875  *
 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
 881  */
 882 int ctdb_detach(struct tevent_context *ev,
 883                 struct ctdb_client_context *client,
 884                 struct timeval timeout, uint32_t db_id);
 885
 886
 887 /**
 888  * @brief Get database id from database context
 889  *
 890  * @param[in] db Database context
 891  * @return database id
 892  */
 893 uint32_t ctdb_db_id(struct ctdb_db_context *db);
 894
 895 /**
 896  * @brief Traverse a database locally on the node
 897  *
 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.
 902  *
 903  * This is useful for replicated databases, since each node has exactly the
 904  * same records.
 905  *
 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
 912  */
 913 int ctdb_db_traverse_local(struct ctdb_db_context *db, bool readonly,
 914                            bool extract_header,
 915                            ctdb_rec_parser_func_t parser, void *private_data);
 916
 917 /**
 918  * @brief Async computation start to a cluster-wide database traverse
 919  *
 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.
 924  *
 925  * This is useful for distributed databases as the records are distributed
 926  * among the cluster nodes.
 927  *
 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
 937  */
 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,
 942                                          uint32_t destnode,
 943                                          struct timeval timeout,
 944                                          ctdb_rec_parser_func_t parser,
 945                                          void *private_data);
 946
 947 /**
 948  * @brief Async computation end to a cluster-wide database traverse
 949  *
 950  * @param[in] req Tevent request
 951  * @param[out] perr errno in case of failure
 952  * @return true on success, false on failure
 953  */
 954 bool ctdb_db_traverse_recv(struct tevent_req *req, int *perr);
 955
 956 /**
 957  * @brief Sync wrapper for a cluster-wide database traverse
 958  *
 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
 968  */
 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);
 974
 975 /**
 976  * @brief Fetch a record from a local database
 977  *
 978  * This function is primarily for internal use.
 979  * Clients should use ctdb_fetch_lock() instead.
 980  *
 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
 986  */
 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);
 990
 991 /**
 992  * @brief Async computation start to fetch a locked record
 993  *
 994  * This function is used to fetch a record from a distributed database.
 995  *
 996  * If the record is already available on the local node, then lock the
 997  * record and return the record handle.
 998  *
 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.
1002  *
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.
1005  *
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
1013  */
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);
1019
1020 /**
1021  * @brief Async computation end to fetch a locked record
1022  *
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
1029  */
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);
1034
1035 /**
1036  * @brief Sync wrapper to fetch a locked record
1037  *
1038  * @see ctdb_fetch_lock_send
1039  *
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
1049  */
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);
1055
1056 /**
1057  * @brief Update a locked record
1058  *
1059  * This function is used to update a record in a distributed database.
1060  *
1061  * This function should NOT be used to store null data, instead use
1062  * ctdb_delete_record().
1063  *
1064  * @param[in] h Record handle
1065  * @param[in] data New record data
1066  * @return 0 on success, errno on failure
1067  */
1068 int ctdb_store_record(struct ctdb_record_handle *h, TDB_DATA data);
1069
1070 /**
1071  * @brief Async computation start to delete a locked record
1072  *
1073  * This function is used to delete a record in a distributed database
1074  *
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
1079  */
1080 struct tevent_req *ctdb_delete_record_send(TALLOC_CTX *mem_ctx,
1081                                            struct tevent_context *ev,
1082                                            struct ctdb_record_handle *h);
1083
1084 /**
1085  * @brief Async computation end to delete a locked record
1086  *
1087  * @param[in] req Tevent request
1088  * @param[out] perr errno in case of failure
1089  * @return true on success, false on failure
1090  */
1091 bool ctdb_delete_record_recv(struct tevent_req *req, int *perr);
1092
1093 /**
1094  * @brief Sync wrapper to delete a locked record
1095  *
1096  * @see ctdb_delete_record_send
1097  *
1098  * @param[in] h Record handle
1099  * @return 0 on success, errno on failure
1100  */
1101 int ctdb_delete_record(struct ctdb_record_handle *h);
1102
1103 /**
1104  * @brief Async computation start to get a global database lock
1105  *
1106  * Functions related to global locks are primarily used internally for
1107  * implementing transaction api.
1108  *
1109  * Clients should use transaction api directly.
1110  * @see ctdb_transaction_start_send
1111  *
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
1120  */
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,
1127                                          bool readonly);
1128
1129 /**
1130  * @brief Async computation end to get a global database lock
1131  *
1132  * @param[in] req Tevent request
1133  * @param[out] perr errno in case of failure
1134  * @return true on success, false on failure
1135  */
1136 bool ctdb_g_lock_lock_recv(struct tevent_req *req, int *perr);
1137
1138 /**
1139  * @brief Async computation start to release a global database lock
1140  *
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
1148  */
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);
1155
1156 /**
1157  * @brief Async computation end to release a global database lock
1158  *
1159  * @param[in] req Tevent request
1160  * @param[out] perr errno in case of failure
1161  * @return true on success, false on failure
1162  */
1163 bool ctdb_g_lock_unlock_recv(struct tevent_req *req, int *perr);
1164
1165 /**
1166  * @brief Async computation start to start a transaction
1167  *
1168  * This function is used to start a transaction on a replicated database.
1169  *
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)
1177  *
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 transaction is committed or cancelled.
1181  *
1182  * Clients should NOT free the transaction handle.
1183  *
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
1191  */
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,
1197                                                bool readonly);
1198
1199 /**
1200  * @brief Async computation end to start a transaction
1201  *
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
1205  */
1206 struct ctdb_transaction_handle *ctdb_transaction_start_recv(
1207                                         struct tevent_req *req,
1208                                         int *perr);
1209
1210 /**
1211  * @brief Sync wrapper to start a transaction
1212  *
1213  * @see ctdb_transaction_start_send
1214  *
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
1223  */
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);
1229
1230 /**
1231  * @brief Fetch a record under a transaction
1232  *
1233  * @see ctdb_transaction_start_send
1234  *
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
1240  */
1241 int ctdb_transaction_fetch_record(struct ctdb_transaction_handle *h,
1242                                   TDB_DATA key,
1243                                   TALLOC_CTX *mem_ctx, TDB_DATA *data);
1244
1245 /**
1246  * @brief Store a record under a transaction
1247  *
1248  * @see ctdb_transaction_start_send
1249  *
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
1254  */
1255 int ctdb_transaction_store_record(struct ctdb_transaction_handle *h,
1256                                   TDB_DATA key, TDB_DATA data);
1257
1258 /**
1259  * @brief Delete a record under a transaction
1260  *
1261  * @see ctdb_transaction_start_send
1262  *
1263  * @param[in] h Transaction handle
1264  * @param[in] key Record key
1265  * @return 0 on success, errno on failure
1266  */
1267 int ctdb_transaction_delete_record(struct ctdb_transaction_handle *h,
1268                                    TDB_DATA key);
1269
1270 /**
1271  * @brief Async computation start to commit a transaction
1272  *
1273  * @see ctdb_transaction_start_send
1274  *
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
1280  */
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);
1286
1287 /**
1288  * @brief Async computation end to commit a transaction
1289  *
1290  * @param[in] req Tevent request
1291  * @param[out] perr errno in case of failure
1292  * @return true on success, false on failure
1293  */
1294 bool ctdb_transaction_commit_recv(struct tevent_req *req, int *perr);
1295
1296 /**
1297  * @brief Sync wrapper to commit a transaction
1298  *
1299  * @see ctdb_transaction_commit_send
1300  *
1301  * @param[in] h Transaction handle
1302  * @return 0 on success, errno on failure
1303  */
1304 int ctdb_transaction_commit(struct ctdb_transaction_handle *h);
1305
1306 /**
1307  * @brief Async computation start to cancel a transaction
1308  *
1309  * @see ctdb_transaction_start_send
1310  *
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
1316  */
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);
1322
1323 /**
1324  * @brief Async computation end to cancel a transaction
1325  *
1326  * @param[in] req Tevent request
1327  * @param[out] perr errno in case of failure
1328  * @return true on success, false on failure
1329  */
1330 bool ctdb_transaction_cancel_recv(struct tevent_req *req, int *perr);
1331
1332 /**
1333  * @brief Sync wrapper to cancel a transaction
1334  *
1335  * @see ctdb_transaction_cancel_send
1336  *
1337  * @param[in] h Transaction handle
1338  * @return 0 on success, errno on failure
1339  */
1340 int ctdb_transaction_cancel(struct ctdb_transaction_handle *h);
1341
1342 /**
1343  * @brief Utility function to extract a list of node ids from nodemap
1344  *
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
1351  */
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);
1355
1356 /**
1357  * @brief Utility function to extract a list of node ids for active nodes
1358  *
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
1364  */
1365 int list_of_active_nodes(struct ctdb_node_map *nodemap, uint32_t exclude_pnn,
1366                          TALLOC_CTX *mem_ctx, uint32_t **pnn_list);
1367
1368 /**
1369  * @brief Utility function to extract a list of node ids for connected nodes
1370  *
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
1376  */
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);
1380
1381 /**
1382  * @brief Construct a new server id
1383  *
1384  * @param[in] client Client connection context
1385  * @param[in] task_id Task id
1386  * @return a new server id
1387  */
1388 struct ctdb_server_id ctdb_client_get_server_id(
1389                                 struct ctdb_client_context *client,
1390                                 uint32_t task_id);
1391
1392 /**
1393  * @brief Check if two server ids are the same
1394  *
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
1398  */
1399 bool ctdb_server_id_equal(struct ctdb_server_id *sid1,
1400                           struct ctdb_server_id *sid2);
1401
1402 /**
1403  * @brief Check if the process with server id exists
1404  *
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
1411  */
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);
1415
1416 #endif /* __CTDB_CLIENT_H__ */