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 succcess, 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 a flag 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 flag is set to true or if the timeout occurs.
 179  *
 180  * This function will return when either
 181  *  - done flag is set to true, or
 182  *  - timeout has occurred.
 183  *
 184  * @param[in] ev Tevent context
 185  * @param[in] done Boolean flag to indicate when to stop waiting
 186  * @param[in] timeout How long to wait
 187  * @return 0 on succes, ETIMEDOUT on timeout, and errno on failure
 188  */
 189 int ctdb_client_wait_timeout(struct tevent_context *ev, bool *done,
 190                              struct timeval timeout);
 191
 192 /**
 193  * @brief Async computation start to wait till recovery is completed
 194  *
 195  * CTDB daemon does not perform many operations while in recovery (especially
 196  * database operations).  This computation allows one to wait till ctdb daemon has
 197  * finished recovery.
 198  *
 199  * @param[in] mem_ctx Talloc memory context
 200  * @param[in] ev Tevent context
 201  * @param[in] client Client connection context
 202  * @return new tevent request, or NULL on failure
 203  */
 204 struct tevent_req *ctdb_recovery_wait_send(TALLOC_CTX *mem_ctx,
 205                                            struct tevent_context *ev,
 206                                            struct ctdb_client_context *client);
 207
 208 /**
 209  * @brief Async computation end to wait till recovery is completed
 210  *
 211  * @param[in] req Tevent request
 212  * @param[out] perr errno in case of failure
 213  * @return true on success, false on failure
 214  */
 215 bool ctdb_recovery_wait_recv(struct tevent_req *req, int *perr);
 216
 217 /**
 218  * @brief Sync wrapper for ctdb_recovery_wait computation
 219  *
 220  * @param[in] ev Tevent context
 221  * @param[in] client Client connection context
 222  * @return true on success, false on failure
 223  */
 224 bool ctdb_recovery_wait(struct tevent_context *ev,
 225                         struct ctdb_client_context *client);
 226
 227 /**
 228  * @brief Async computation start to migrate a database record
 229  *
 230  * This sends a request to ctdb daemon to migrate a database record to
 231  * the local node.  CTDB daemon will locate the data master for the record
 232  * and will migrate record (and the data master) to the current node.
 233  *
 234  * @see ctdb_fetch_lock_send
 235  *
 236  * @param[in] mem_ctx Talloc memory context
 237  * @param[in] ev  Tevent context
 238  * @param[in] client Client connection context
 239  * @param[in] request CTDB request data
 240  * @return a new tevent req, or NULL on failure
 241  */
 242 struct tevent_req *ctdb_client_call_send(TALLOC_CTX *mem_ctx,
 243                                          struct tevent_context *ev,
 244                                          struct ctdb_client_context *client,
 245                                          struct ctdb_req_call *request);
 246
 247 /**
 248  * @brief Async computation end to migrate a database record
 249  *
 250  * @param[in] req Tevent request
 251  * @param[in] mem_ctx Talloc memory context
 252  * @param[out] reply CTDB reply data
 253  * @param[out] perr errno in case of failure
 254  * @return true on success, false on failure
 255  */
 256 bool ctdb_client_call_recv(struct tevent_req *req, TALLOC_CTX *mem_ctx,
 257                            struct ctdb_reply_call **reply, int *perr);
 258
 259
 260 /**
 261  * @brief Async computation start to send a message to remote client(s)
 262  *
 263  * This sends a message to ctdb clients on a remote node.  All the
 264  * messages are associated with a specific SRVID.  All the clients on the
 265  * remote node listening to that SRVID, will get the message.
 266  *
 267  * Clients can register and deregister for messages for a SRVID using
 268  * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
 269  *
 270  * @see ctdb_client_set_message_handler_send,
 271  *      ctdb_client_remove_message_handler_send
 272  *
 273  * @param[in] mem_ctx Talloc memory context
 274  * @param[in] ev Tevent context
 275  * @param[in] client Client connection context
 276  * @param[in] destnode Remote node id
 277  * @param[in] message Message to send
 278  * @return a new tevent req on success, NULL on failure
 279  */
 280 struct tevent_req *ctdb_client_message_send(TALLOC_CTX *mem_ctx,
 281                                             struct tevent_context *ev,
 282                                             struct ctdb_client_context *client,
 283                                             uint32_t destnode,
 284                                             struct ctdb_req_message *message);
 285
 286 /**
 287  * @brief Async computation end to send a message to remote client(s)
 288  *
 289  * @param[in] req Tevent request
 290  * @param[out] perr errno in case of failure
 291  * @return true on success, false on failure
 292  */
 293 bool ctdb_client_message_recv(struct tevent_req *req, int *perr);
 294
 295 /**
 296  * @brief Sync wrapper to send a message to client(s) on remote node
 297  *
 298  * @param[in] mem_ctx Talloc memory context
 299  * @param[in] ev Tevent context
 300  * @param[in] client Client connection context
 301  * @param[in] destnode Node id
 302  * @param[in] message Message to send
 303  */
 304 int ctdb_client_message(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 305                         struct ctdb_client_context *client,
 306                         uint32_t destnode, struct ctdb_req_message *message);
 307
 308 /**
 309  * @brief Async computation start to send a message to multiple nodes
 310  *
 311  * This sends a message to ctdb clients on multiple remote nodes.  All the
 312  * messages are associated with a specific SRVID.  All the clients on remote
 313  * nodes listening to that SRVID, will get the message.
 314  *
 315  * Clients can register and deregister for messages for a SRVID using
 316  * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
 317  *
 318  * @see ctdb_client_set_message_handler_send,
 319  *      ctdb_client_remove_message_handler_send
 320  *
 321  * @param[in] mem_ctx Talloc memory context
 322  * @param[in] ev Tevent context
 323  * @param[in] client Client connection context
 324  * @param[in] pnn_list List of node ids
 325  * @param[in] count Number of node ids
 326  * @param[in] message Message to send
 327  * @return a new tevent req on success, NULL on failure
 328  */
 329 struct tevent_req *ctdb_client_message_multi_send(
 330                                 TALLOC_CTX *mem_ctx,
 331                                 struct tevent_context *ev,
 332                                 struct ctdb_client_context *client,
 333                                 uint32_t *pnn_list, int count,
 334                                 struct ctdb_req_message *message);
 335
 336 /**
 337  * @brief Async computation end to send a message to multiple nodes
 338  *
 339  * @param[in] req Tevent request
 340  * @param[out] perr errno in case of failure
 341  * @param[in] mem_ctx Talloc memory context
 342  * @param[out] perr_list The status from each node id
 343  * @return true on success, false on failure
 344  *
 345  * If perr_list is not NULL, then the status (0 on success, errno on failure)
 346  * of sending message to each of the node in the specified node list.  The
 347  * perr_list is an array of the same size as of pnn_list.
 348  */
 349 bool ctdb_client_message_multi_recv(struct tevent_req *req, int *perr,
 350                                     TALLOC_CTX *mem_ctx, int **perr_list);
 351
 352 /**
 353  * @brief Sync wrapper to send a message to multiple nodes
 354  *
 355  * @param[in] mem_ctx Talloc memory context
 356  * @param[in] ev Tevent context
 357  * @param[in] client Client connection context
 358  * @param[in] pnn_list List of node ids
 359  * @param[in] count Number of node ids
 360  * @param[in] message Message to send
 361  * @param[out] perr_list The status from each node id
 362  * @return 0 on success, errno on failure
 363  */
 364 int ctdb_client_message_multi(TALLOC_CTX *mem_ctx,
 365                               struct tevent_context *ev,
 366                               struct ctdb_client_context *client,
 367                               uint32_t *pnn_list, int count,
 368                               struct ctdb_req_message *message,
 369                               int **perr_list);
 370
 371 /**
 372  * @brief Async computation start to receive messages for a SRVID
 373  *
 374  * This computation informs ctdb that the client is interested in all messages
 375  * for a specific SRVID.
 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] srvid SRVID
 381  * @param[in] handler Callback function to call when a message is received
 382  * @param[in] private_data Private data for callback
 383  * @return a new tevent req on success, NULL on failure
 384  */
 385 struct tevent_req *ctdb_client_set_message_handler_send(
 386                                         TALLOC_CTX *mem_ctx,
 387                                         struct tevent_context *ev,
 388                                         struct ctdb_client_context *client,
 389                                         uint64_t srvid,
 390                                         srvid_handler_fn handler,
 391                                         void *private_data);
 392
 393 /**
 394  * @brief Async computation end to receive messages for a SRVID
 395  *
 396  * @param[in] req Tevent request
 397  * @param[out] perr errno in case of failure
 398  * @return true on success, false on failure
 399  */
 400 bool ctdb_client_set_message_handler_recv(struct tevent_req *req, int *perr);
 401
 402 /**
 403  * Sync wrapper to receive messages for a SRVID
 404  *
 405  * @param[in] ev Tevent context
 406  * @param[in] client Client connection context
 407  * @param[in] srvid SRVID
 408  * @param[in] handler Callback function to call when a message is received
 409  * @param[in] private_data Private data for callback
 410  * @return 0 on success, errno on failure
 411  */
 412 int ctdb_client_set_message_handler(struct tevent_context *ev,
 413                                     struct ctdb_client_context *client,
 414                                     uint64_t srvid, srvid_handler_fn handler,
 415                                     void *private_data);
 416
 417 /**
 418  * @brief Async computation start to stop receiving messages for a SRVID
 419  *
 420  * This computation informs ctdb that the client is no longer interested in
 421  * messages for a specific SRVID.
 422  *
 423  * @param[in] mem_ctx Talloc memory context
 424  * @param[in] ev Tevent context
 425  * @param[in] client Client connection context
 426  * @param[in] srvid SRVID
 427  * @param[in] private_data Private data used to register callback
 428  * @return a new tevent req on success, NULL on failure
 429  */
 430 struct tevent_req *ctdb_client_remove_message_handler_send(
 431                                         TALLOC_CTX *mem_ctx,
 432                                         struct tevent_context *ev,
 433                                         struct ctdb_client_context *client,
 434                                         uint64_t srvid,
 435                                         void *private_data);
 436
 437 /**
 438  * @brief Async computation end to stop receiving messages for a SRVID
 439  *
 440  * @param[in] req Tevent request
 441  * @param[out] perr errno in case of failure
 442  * @return true on success, false on failure
 443  */
 444 bool ctdb_client_remove_message_handler_recv(struct tevent_req *req,
 445                                              int *perr);
 446
 447 /**
 448  * Sync wrapper to stop receiving messages for a SRVID
 449  *
 450  * @param[in] ev Tevent context
 451  * @param[in] client Client connection context
 452  * @param[in] srvid SRVID
 453  * @param[in] private_data Private data used to register callback
 454  * @return 0 on success, errno on failure
 455  */
 456 int ctdb_client_remove_message_handler(struct tevent_context *ev,
 457                                        struct ctdb_client_context *client,
 458                                        uint64_t srvid, void *private_data);
 459
 460 /**
 461  * @brief Async computation start to send a control to ctdb daemon
 462  *
 463  * @param[in] mem_ctx Talloc memory context
 464  * @param[in] ev Tevent context
 465  * @param[in] client Client connection context
 466  * @param[in] destnode Node id
 467  * @param[in] timeout How long to wait
 468  * @param[in] request Control request
 469  * @return a new tevent req on success, NULL on failure
 470  */
 471 struct tevent_req *ctdb_client_control_send(TALLOC_CTX *mem_ctx,
 472                                             struct tevent_context *ev,
 473                                             struct ctdb_client_context *client,
 474                                             uint32_t destnode,
 475                                             struct timeval timeout,
 476                                             struct ctdb_req_control *request);
 477
 478 /**
 479  * @brief Async computation end to send a control to ctdb daemon
 480  *
 481  * @param[in] req Tevent request
 482  * @param[out] perr errno in case of failure
 483  * @param[in] mem_ctx Talloc memory context
 484  * @param[out] preply Control reply
 485  * @return true on success, false on failure
 486  */
 487 bool ctdb_client_control_recv(struct tevent_req *req, int *perr,
 488                               TALLOC_CTX *mem_ctx,
 489                               struct ctdb_reply_control **preply);
 490
 491 /**
 492  * @brief Sync wrapper to send a control to ctdb daemon
 493  *
 494  * @param[in] mem_ctx Talloc memory context
 495  * @param[in] ev Tevent context
 496  * @param[in] client Client connection context
 497  * @param[in] destnode Node id
 498  * @param[in] timeout How long to wait
 499  * @param[in] request Control request
 500  * @param[out] preply Control reply
 501  * @return 0 on success, errno on failure
 502  */
 503 int ctdb_client_control(TALLOC_CTX *mem_ctx,
 504                         struct tevent_context *ev,
 505                         struct ctdb_client_context *client,
 506                         uint32_t destnode,
 507                         struct timeval timeout,
 508                         struct ctdb_req_control *request,
 509                         struct ctdb_reply_control **preply);
 510
 511 /**
 512  * @brief Async computation start to send a control to multiple nodes
 513  *
 514  * @param[in] mem_ctx Talloc memory context
 515  * @param[in] ev Tevent context
 516  * @param[in] client Client connection context
 517  * @param[in] pnn_list List of node ids
 518  * @param[in] count Number of node ids
 519  * @param[in] timeout How long to wait
 520  * @param[in] request Control request
 521  * @return a new tevent req on success, NULL on failure
 522  */
 523 struct tevent_req *ctdb_client_control_multi_send(
 524                                 TALLOC_CTX *mem_ctx,
 525                                 struct tevent_context *ev,
 526                                 struct ctdb_client_context *client,
 527                                 uint32_t *pnn_list, int count,
 528                                 struct timeval timeout,
 529                                 struct ctdb_req_control *request);
 530
 531 /**
 532  * @brief Async computation end to send a control to multiple nodes
 533  *
 534  * @param[in] req Tevent request
 535  * @param[out] perr errno in case of failure
 536  * @param[in] mem_ctx Talloc memory context
 537  * @param[out] perr_list Status from each node
 538  * @param[out] preply Control reply from each node
 539  * @return true on success, false on failure
 540  */
 541 bool ctdb_client_control_multi_recv(struct tevent_req *req, int *perr,
 542                                     TALLOC_CTX *mem_ctx, int **perr_list,
 543                                     struct ctdb_reply_control ***preply);
 544
 545 /**
 546  * @brief Sync wrapper to send a control to multiple nodes
 547  *
 548  * @param[in] mem_ctx Talloc memory context
 549  * @param[in] ev Tevent context
 550  * @param[in] client Client connection context
 551  * @param[in] pnn_list List of node ids
 552  * @param[in] count Number of node ids
 553  * @param[in] timeout How long to wait
 554  * @param[in] request Control request
 555  * @param[out] perr_list Status from each node
 556  * @param[out] preply Control reply from each node
 557  * @return 0 on success, errno on failure
 558  */
 559 int ctdb_client_control_multi(TALLOC_CTX *mem_ctx,
 560                               struct tevent_context *ev,
 561                               struct ctdb_client_context *client,
 562                               uint32_t *pnn_list, int count,
 563                               struct timeval timeout,
 564                               struct ctdb_req_control *request,
 565                               int **perr_list,
 566                               struct ctdb_reply_control ***preply);
 567
 568 /**
 569  * @brief Check err_list for errors
 570  *
 571  * This is a convenience function to parse the err_list returned from
 572  * functions that send requests to multiple nodes.
 573  *
 574  * If status from any of the node is non-zero, then return first non-zero
 575  * status.
 576  *
 577  * If status from all the nodes is 0, then return 0.
 578  *
 579  * @param[in] pnn_list List of node ids
 580  * @param[in] count Number of node ids
 581  * @param[in] err_list Status from each node
 582  * @param[out] pnn Node id in case of failure
 583  * @return 0 if no failures, status from first failure
 584  */
 585 int ctdb_client_control_multi_error(uint32_t *pnn_list, int count,
 586                                     int *err_list, uint32_t *pnn);
 587
 588 /**
 589  * @brief Async computation start to setup a tunnel endpoint
 590  *
 591  * This computation sets up a tunnel endpoint corresponding to a tunnel_id.
 592  * A tunnel is a ctdb transport to deliver new protocol between endpoints.
 593  *
 594  * For two endpoints to communicate using new protocol,
 595  * 1. Set up tunnel endpoints
 596  * 2. Send requests
 597  * 3. Send replies
 598  * 4. Destroy tunnel endpoints
 599  *
 600  * @param[in] mem_ctx Talloc memory context
 601  * @param[in] ev Tevent context
 602  * @param[in] client Client connection context
 603  * @param[in] tunnel_id Unique tunnel id
 604  * @param[in] callback Callback function to call when a message is received
 605  * @param[in] private_data Private data for callback
 606  * @return a new tevent req on success, NULL on failure
 607  */
 608 struct tevent_req *ctdb_tunnel_setup_send(TALLOC_CTX *mem_ctx,
 609                                           struct tevent_context *ev,
 610                                           struct ctdb_client_context *client,
 611                                           uint64_t tunnel_id,
 612                                           ctdb_tunnel_callback_func_t callback,
 613                                           void *private_data);
 614
 615 /**
 616  * @brief Async computation end to setup a tunnel
 617  *
 618  * @param[in] req Tevent request
 619  * @param[in] perr errno in case of failure
 620  * @param[out] result A new tunnel context
 621  * @return true on success, false on failure
 622  *
 623  * Tunnel context should never be freed by user.
 624  */
 625 bool ctdb_tunnel_setup_recv(struct tevent_req *req, int *perr,
 626                             struct ctdb_tunnel_context **result);
 627
 628 /**
 629  * @brief Sync wrapper for ctdb_tunnel_setup computation
 630  *
 631  * @param[in] mem_ctx Talloc memory context
 632  * @param[in] ev Tevent context
 633  * @param[in] client Client connection context
 634  * @param[in] tunnel_id Unique tunnel id
 635  * @param[in] callback Callback function to call when a message is received
 636  * @param[in] private_data Private data for callback
 637  * @param[out] result A new tunnel context
 638  * @return 0 on success, errno on failure
 639  */
 640 int ctdb_tunnel_setup(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 641                       struct ctdb_client_context *client, uint64_t tunnel_id,
 642                       ctdb_tunnel_callback_func_t callback, void *private_data,
 643                       struct ctdb_tunnel_context **result);
 644
 645 /**
 646  * @brief Async computation start to destroy a tunnel endpoint
 647  *
 648  * This computation destroys the tunnel endpoint.
 649  *
 650  * @param[in] mem_ctx Talloc memory context
 651  * @param[in] ev Tevent context
 652  * @param[in] tctx Tunnel context
 653  * @return a new tevent req on success, NULL on failure
 654  */
 655 struct tevent_req *ctdb_tunnel_destroy_send(TALLOC_CTX *mem_ctx,
 656                                             struct tevent_context *ev,
 657                                             struct ctdb_tunnel_context *tctx);
 658
 659 /**
 660  * @brief Async computation end to destroy a tunnel endpoint
 661  *
 662  * @param[in] req Tevent request
 663  * @param[out] perr errno in case of failure
 664  * @return true on success, false on failure
 665  */
 666 bool ctdb_tunnel_destroy_recv(struct tevent_req *req, int *perr);
 667
 668 /**
 669  * @brief Sync wrapper for ctdb_tunnel_destroy computation
 670  *
 671  * @param[in] ev Tevent context
 672  * @param[in] tctx Tunnel context
 673  * @return 0 on success, errno on failure
 674  */
 675 int ctdb_tunnel_destroy(struct tevent_context *ev,
 676                         struct ctdb_tunnel_context *tctx);
 677
 678 /**
 679  * @brief Async computation start to send a request via a tunnel
 680  *
 681  * @param[in] mem_ctx Talloc memory context
 682  * @param[in] ev Tevent context
 683  * @param[in] tctx Tunnel context
 684  * @param[in] destnode PNN of destination
 685  * @param[in] timeout How long to wait
 686  * @param[in] buf Message to send
 687  * @param[in] buflen Size of the message to send
 688  * @param[in] wait_for_reply Whether to wait for reply
 689  * @return a new tevent req on success, NULL on failure
 690  */
 691 struct tevent_req *ctdb_tunnel_request_send(TALLOC_CTX *mem_ctx,
 692                                             struct tevent_context *ev,
 693                                             struct ctdb_tunnel_context *tctx,
 694                                             int destnode,
 695                                             struct timeval timeout,
 696                                             uint8_t *buf, size_t buflen,
 697                                             bool wait_for_reply);
 698
 699 /**
 700  * @brief Async computation end to send a request via a tunnel
 701  *
 702  * @param[in] req Tevent request
 703  * @param[out] perr errno in case of failure
 704  * @param[in] mem_ctx Talloc context
 705  * @param[out] buf Reply data if expected
 706  * @param[out] buflen Size of reply data if expected
 707  * @return true on success, false on failure
 708  */
 709 bool ctdb_tunnel_request_recv(struct tevent_req *req, int *perr,
 710                               TALLOC_CTX *mem_ctx, uint8_t **buf,
 711                               size_t *buflen);
 712
 713 /**
 714  * @brief Sync wrapper for ctdb_tunnel_request computation
 715  *
 716  * @param[in] mem_ctx Talloc memory context
 717  * @param[in] ev Tevent context
 718  * @param[in] tctx Tunnel context
 719  * @param[in] destnode PNN of destination
 720  * @param[in] timeout How long to wait
 721  * @param[in] buf Message to send
 722  * @param[in] buflen Size of the message to send
 723  * @param[in] wait_for_reply Whether to wait for reply
 724  * @return 0 on success, errno on failure
 725  */
 726 int ctdb_tunnel_request(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 727                         struct ctdb_tunnel_context *tctx, int destnode,
 728                         struct timeval timeout, uint8_t *buf, size_t buflen,
 729                         bool wait_for_reply);
 730
 731 /**
 732  * @brief Async computation start to send a reply via a tunnel
 733  *
 734  * @param[in] mem_ctx Talloc memory context
 735  * @param[in] ev Tevent context
 736  * @param[in] tctx Tunnel context
 737  * @param[in] destnode PNN of destination
 738  * @param[in] reqid Request id
 739  * @param[in] timeout How long to wait
 740  * @param[in] buf Reply data
 741  * @param[in] buflen Size of reply data
 742  * @return a new tevent req on success, NULL on failure
 743  */
 744 struct tevent_req *ctdb_tunnel_reply_send(TALLOC_CTX *mem_ctx,
 745                                           struct tevent_context *ev,
 746                                           struct ctdb_tunnel_context *tctx,
 747                                           int destnode, uint32_t reqid,
 748                                           struct timeval timeout,
 749                                           uint8_t *buf, size_t buflen);
 750
 751 /**
 752  * @brief Async computation end to send a reply via a tunnel
 753  *
 754  * @param[in] req Tevent request
 755  * @param[out] perr errno in case of failure
 756  * @return true on success, false on failure
 757  */
 758 bool ctdb_tunnel_reply_recv(struct tevent_req *req, int *perr);
 759
 760 /**
 761  * @brief Sync wrapper for ctdb_tunnel_reply computation
 762  *
 763  * @param[in] mem_ctx Talloc memory context
 764  * @param[in] ev Tevent context
 765  * @param[in] tctx Tunnel context
 766  * @param[in] destnode PNN of destination
 767  * @param[in] reqid Request id
 768  * @param[in] timeout How long to wait
 769  * @param[in] buf Reply data
 770  * @param[in] buflen Size of reply data
 771  * @return 0 on success, errno on failure
 772  */
 773 int ctdb_tunnel_reply(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 774                       struct ctdb_tunnel_context *tctx, int destnode,
 775                       uint32_t reqid, struct timeval timeout,
 776                       uint8_t *buf, size_t buflen);
 777
 778 /**
 779  * @brief Async computation start to attach a database
 780  *
 781  * @param[in] mem_ctx Talloc memory context
 782  * @param[in] ev Tevent context
 783  * @param[in[ client Client connection context
 784  * @param[in] timeout How long to wait
 785  * @param[in] db_name Name of the database
 786  * @param[in] db_flags Database flags
 787  * @return a new tevent req on success, NULL on failure
 788  */
 789 struct tevent_req *ctdb_attach_send(TALLOC_CTX *mem_ctx,
 790                                     struct tevent_context *ev,
 791                                     struct ctdb_client_context *client,
 792                                     struct timeval timeout,
 793                                     const char *db_name, uint8_t db_flags);
 794
 795 /**
 796  * @brief Async computation end to attach a database
 797  *
 798  * @param[in] req Tevent request
 799  * @param[out] perr errno in case of failure
 800  * @param[out] result New database context
 801  * @return true on success, false on failure
 802  */
 803 bool ctdb_attach_recv(struct tevent_req *req, int *perr,
 804                       struct ctdb_db_context **result);
 805
 806 /**
 807  * @brief Sync wrapper to attach a database
 808  *
 809  * @param[in] ev Tevent context
 810  * @param[in[ client Client connection context
 811  * @param[in] timeout How long to wait
 812  * @param[in] db_name Name of the database
 813  * @param[in] db_flags Database flags
 814  * @param[out] result New database context
 815  * @return 0 on success, errno on failure
 816  */
 817 int ctdb_attach(struct tevent_context *ev,
 818                 struct ctdb_client_context *client,
 819                 struct timeval timeout,
 820                 const char *db_name, uint8_t db_flags,
 821                 struct ctdb_db_context **result);
 822
 823 /**
 824  * @brief Async computation start to detach a database
 825  *
 826  * Only volatile databases can be detached at runtime.
 827  *
 828  * @param[in] mem_ctx Talloc memory context
 829  * @param[in] ev Tevent context
 830  * @param[in[ client Client connection context
 831  * @param[in] timeout How long to wait
 832  * @param[in] db_id Database id
 833  * @return a new tevent req on success, NULL on failure
 834  */
 835 struct tevent_req *ctdb_detach_send(TALLOC_CTX *mem_ctx,
 836                                     struct tevent_context *ev,
 837                                     struct ctdb_client_context *client,
 838                                     struct timeval timeout, uint32_t db_id);
 839
 840 /**
 841  * @brief Async computation end to detach a database
 842  *
 843  * @param[in] req Tevent request
 844  * @param[out] perr errno in case of failure
 845  * @return true on success, false on failure
 846  */
 847 bool ctdb_detach_recv(struct tevent_req *req, int *perr);
 848
 849 /**
 850  * @brief Sync wrapper to detach a database
 851  *
 852  * Only volatile databases can be detached at runtime.
 853  *
 854  * @param[in] ev Tevent context
 855  * @param[in[ client Client connection context
 856  * @param[in] timeout How long to wait
 857  * @param[in] db_id Database id
 858  * @return 0 on success, errno on failure
 859  */
 860 int ctdb_detach(struct tevent_context *ev,
 861                 struct ctdb_client_context *client,
 862                 struct timeval timeout, uint32_t db_id);
 863
 864
 865 /**
 866  * @brief Get database id from database context
 867  *
 868  * @param[in] db Database context
 869  * @return database id
 870  */
 871 uint32_t ctdb_db_id(struct ctdb_db_context *db);
 872
 873 /**
 874  * @brief Traverse a database locally on the node
 875  *
 876  * This function traverses a database locally on the node and for each record
 877  * calls the parser function.  If the parser function returns 1, the traverse
 878  * will terminate.  If parser function returns 0, the traverse will continue
 879  * till all records in database are parsed.
 880  *
 881  * This is useful for replicated databases, since each node has exactly the
 882  * same records.
 883  *
 884  * @param[in] db Database context
 885  * @param[in] readonly Is the traversal for reading or updating
 886  * @param[in] extract_header Whether to extract ltdb header from record data
 887  * @param[in] parser Record parsing function
 888  * @param[in] private_data Private data for parser function
 889  * @return 0 on success, non-zero return value from parser function
 890  */
 891 int ctdb_db_traverse_local(struct ctdb_db_context *db, bool readonly,
 892                            bool extract_header,
 893                            ctdb_rec_parser_func_t parser, void *private_data);
 894
 895 /**
 896  * @brief Async computation start to a cluster-wide database traverse
 897  *
 898  * This function traverses a database on all the nodes 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 all on nodes are parsed.
 902  *
 903  * This is useful for distributed databases as the records are distributed
 904  * among the cluster nodes.
 905  *
 906  * @param[in] mem_ctx Talloc memory context
 907  * @param[in] ev Tevent context
 908  * @param[in] client Client connection context
 909  * @param[in] db Database context
 910  * @param[in] destnode Node id
 911  * @param[in] timeout How long to wait
 912  * @param[in] parser Record parser function
 913  * @param[in] private_data Private data for parser
 914  * @return a new tevent req on success, NULL on failure
 915  */
 916 struct tevent_req *ctdb_db_traverse_send(TALLOC_CTX *mem_ctx,
 917                                          struct tevent_context *ev,
 918                                          struct ctdb_client_context *client,
 919                                          struct ctdb_db_context *db,
 920                                          uint32_t destnode,
 921                                          struct timeval timeout,
 922                                          ctdb_rec_parser_func_t parser,
 923                                          void *private_data);
 924
 925 /**
 926  * @brief Async computation end to a cluster-wide database traverse
 927  *
 928  * @param[in] req Tevent request
 929  * @param[out] perr errno in case of failure
 930  * @return true on success, false on failure
 931  */
 932 bool ctdb_db_traverse_recv(struct tevent_req *req, int *perr);
 933
 934 /**
 935  * @brief Sync wrapper for a cluster-wide database traverse
 936  *
 937  * @param[in] mem_ctx Talloc memory context
 938  * @param[in] ev Tevent context
 939  * @param[in] client Client connection context
 940  * @param[in] db Database context
 941  * @param[in] destnode Node id
 942  * @param[in] timeout How long to wait
 943  * @param[in] parser Record parser function
 944  * @param[in] private_data Private data for parser
 945  * @return 0 on success, errno on failure or non-zero status from parser
 946  */
 947 int ctdb_db_traverse(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 948                      struct ctdb_client_context *client,
 949                      struct ctdb_db_context *db,
 950                      uint32_t destnode, struct timeval timeout,
 951                      ctdb_rec_parser_func_t parser, void *private_data);
 952
 953 /**
 954  * @brief Fetch a record from a local database
 955  *
 956  * This function is primarily for internal use.
 957  * Clients should use ctdb_fetch_lock() instead.
 958  *
 959  * @param[in] db Database context
 960  * @param[in] key Record key
 961  * @param[out] header Record header
 962  * @param[in] mem_ctx Talloc memory context
 963  * @param[out] data Record data
 964  */
 965 int ctdb_ltdb_fetch(struct ctdb_db_context *db, TDB_DATA key,
 966                     struct ctdb_ltdb_header *header,
 967                     TALLOC_CTX *mem_ctx, TDB_DATA *data);
 968
 969 /**
 970  * @brief Async computation start to fetch a locked record
 971  *
 972  * This function is used to fetch a record from a distributed database.
 973  *
 974  * If the record is already available on the local node, then lock the
 975  * record and return the record handle.
 976  *
 977  * If the record is not available on the local node, send a CTDB request to
 978  * migrate the record.  Once the record is migrated to the local node, lock
 979  * the record and return the record handle.
 980  *
 981  * At the end of the computation, a record handle is returned which holds
 982  * the record lock.  When the record handle is freed, the record is unlocked.
 983  *
 984  * @param[in] mem_ctx Talloc memory context
 985  * @param[in] ev Tevent context
 986  * @param[in] client Client context
 987  * @param[in] db Database context
 988  * @param[in] key Record key
 989  * @param[in] readonly Whether to request readonly copy of the record
 990  * @return a new tevent req on success, NULL on failure
 991  */
 992 struct tevent_req *ctdb_fetch_lock_send(TALLOC_CTX *mem_ctx,
 993                                         struct tevent_context *ev,
 994                                         struct ctdb_client_context *client,
 995                                         struct ctdb_db_context *db,
 996                                         TDB_DATA key, bool readonly);
 997
 998 /**
 999  * @brief Async computation end to fetch a locked record
1000  *
1001  * @param[in] req Tevent request
1002  * @param[out] header Record header
1003  * @param[in] mem_ctx Talloc memory context
1004  * @param[out] data Record data
1005  * @param[out] perr errno in case of failure
1006  * @return a new record handle, NULL on failure
1007  */
1008 struct ctdb_record_handle *ctdb_fetch_lock_recv(struct tevent_req *req,
1009                                                 struct ctdb_ltdb_header *header,
1010                                                 TALLOC_CTX *mem_ctx,
1011                                                 TDB_DATA *data, int *perr);
1012
1013 /**
1014  * @brief Sync wrapper to fetch a locked record
1015  *
1016  * @see ctdb_fetch_lock_send
1017  *
1018  * @param[in] mem_ctx Talloc memory context
1019  * @param[in] ev Tevent context
1020  * @param[in] client Client context
1021  * @param[in] db Database context
1022  * @param[in] key Record key
1023  * @param[in] readonly Whether to request readonly copy of the record
1024  * @param[out] header Record header
1025  * @param[out] data Record data
1026  * return 0 on success, errno on failure
1027  */
1028 int ctdb_fetch_lock(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
1029                     struct ctdb_client_context *client,
1030                     struct ctdb_db_context *db, TDB_DATA key, bool readonly,
1031                     struct ctdb_record_handle **out,
1032                     struct ctdb_ltdb_header *header, TDB_DATA *data);
1033
1034 /**
1035  * @brief Update a locked record
1036  *
1037  * This function is used to update a record in a distributed database.
1038  *
1039  * This function should NOT be used to store null data, instead use
1040  * ctdb_delete_record().
1041  *
1042  * @param[in] h Record handle
1043  * @param[in] data New record data
1044  * @return 0 on success, errno on failure
1045  */
1046 int ctdb_store_record(struct ctdb_record_handle *h, TDB_DATA data);
1047
1048 /**
1049  * @brief Async computation start to delete a locked record
1050  *
1051  * This function is used to delete a record in a distributed database
1052  *
1053  * @param[in] mem_ctx Talloc memory context
1054  * @param[in] ev Tevent context
1055  * @param[in] h Record handle
1056  * @return a new tevent req on success, NULL on failure
1057  */
1058 struct tevent_req *ctdb_delete_record_send(TALLOC_CTX *mem_ctx,
1059                                            struct tevent_context *ev,
1060                                            struct ctdb_record_handle *h);
1061
1062 /**
1063  * @brief Async computation end to delete a locked record
1064  *
1065  * @param[in] req Tevent request
1066  * @param[out] perr errno in case of failure
1067  * @return true on success, false on failure
1068  */
1069 bool ctdb_delete_record_recv(struct tevent_req *req, int *perr);
1070
1071 /**
1072  * @brief Sync wrapper to delete a locked record
1073  *
1074  * @see ctdb_delete_record_send
1075  *
1076  * @param[in] h Record handle
1077  * @return 0 on success, errno on failure
1078  */
1079 int ctdb_delete_record(struct ctdb_record_handle *h);
1080
1081 /**
1082  * @brief Async computation start to get a global database lock
1083  *
1084  * Functions related to global locks are primarily used internally for
1085  * implementing transaction api.
1086  *
1087  * Clients should use transaction api directly.
1088  * @see ctdb_transaction_start_send
1089  *
1090  * @param[in] mem_ctx Talloc memory context
1091  * @param[in] ev Tevent context
1092  * @param[in] client Client context
1093  * @param[in] db Database context for g_lock.tdb
1094  * @param[in] keyname Record key
1095  * @param[in] sid Server id
1096  * @param[in] readonly Lock type
1097  * @return a new tevent req on success, NULL on failure
1098  */
1099 struct tevent_req *ctdb_g_lock_lock_send(TALLOC_CTX *mem_ctx,
1100                                          struct tevent_context *ev,
1101                                          struct ctdb_client_context *client,
1102                                          struct ctdb_db_context *db,
1103                                          const char *keyname,
1104                                          struct ctdb_server_id *sid,
1105                                          bool readonly);
1106
1107 /**
1108  * @brief Async computation end to get a global database lock
1109  *
1110  * @param[in] req Tevent request
1111  * @param[out] perr errno in case of failure
1112  * @return true on success, false on failure
1113  */
1114 bool ctdb_g_lock_lock_recv(struct tevent_req *req, int *perr);
1115
1116 /**
1117  * @brief Async computation start to release a global database lock
1118  *
1119  * @param[in] mem_ctx Talloc memory context
1120  * @param[in] ev Tevent context
1121  * @param[in] client Client connection context
1122  * @param[in] db Database context
1123  * @param[in] keyname Record key
1124  * @param[in] sid Server id
1125  * @return a new tevent req on success, NULL on failure
1126  */
1127 struct tevent_req *ctdb_g_lock_unlock_send(TALLOC_CTX *mem_ctx,
1128                                            struct tevent_context *ev,
1129                                            struct ctdb_client_context *client,
1130                                            struct ctdb_db_context *db,
1131                                            const char *keyname,
1132                                            struct ctdb_server_id sid);
1133
1134 /**
1135  * @brief Async computation end to release a global database lock
1136  *
1137  * @param[in] req Tevent request
1138  * @param[out] perr errno in case of failure
1139  * @return true on success, false on failure
1140  */
1141 bool ctdb_g_lock_unlock_recv(struct tevent_req *req, int *perr);
1142
1143 /**
1144  * @brief Async computation start to start a transaction
1145  *
1146  * This function is used to start a transaction on a replicated database.
1147  *
1148  * To perform any updates on a replicated database
1149  * - start transaction
1150  * - fetch record (ctdb_transaction_fetch_record)
1151  * - store record (ctdb_transaction_store_record)
1152  * - delete record (ctdb_transaction_delete_record)
1153  * - commit transaction (ctdb_transaction_commit_send), or
1154  * - cancel transaction (ctdb_transaction_cancel_send)
1155  *
1156  * Starting a transaction will return a transaction handle.  This is used
1157  * for updating records under a transaction.  This handle is automatically
1158  * freed once the transacion is committed or cancelled.
1159  *
1160  * Clients should NOT free the transaction handle.
1161  *
1162  * @param[in] mem_ctx Talloc memory context
1163  * @param[in] ev Tevent context
1164  * @param[in] client Client connection context
1165  * @param[in] timeout How long to wait
1166  * @param[in] db Database context
1167  * @param[in] readonly Is transaction readonly
1168  * @return a new tevent req on success, NULL on failure
1169  */
1170 struct tevent_req *ctdb_transaction_start_send(TALLOC_CTX *mem_ctx,
1171                                                struct tevent_context *ev,
1172                                                struct ctdb_client_context *client,
1173                                                struct timeval timeout,
1174                                                struct ctdb_db_context *db,
1175                                                bool readonly);
1176
1177 /**
1178  * @brief Async computation end to start a transaction
1179  *
1180  * @param[in] req Tevent request
1181  * @param[out] perr errno in case of failure
1182  * @return a new transaction handle on success, NULL on failure
1183  */
1184 struct ctdb_transaction_handle *ctdb_transaction_start_recv(
1185                                         struct tevent_req *req,
1186                                         int *perr);
1187
1188 /**
1189  * @brief Sync wrapper to start a transaction
1190  *
1191  * @see ctdb_transaction_start_send
1192  *
1193  * @param[in] mem_ctx Talloc memory context
1194  * @param[in] ev Tevent context
1195  * @param[in] client Client connection context
1196  * @param[in] timeout How long to wait
1197  * @param[in] db Database context
1198  * @param[in] readonly Is transaction readonly
1199  * @param[out] result a new transaction handle
1200  * @return 0 on success, errno on failure
1201  */
1202 int ctdb_transaction_start(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
1203                            struct ctdb_client_context *client,
1204                            struct timeval timeout,
1205                            struct ctdb_db_context *db, bool readonly,
1206                            struct ctdb_transaction_handle **result);
1207
1208 /**
1209  * @brief Fetch a record under a transaction
1210  *
1211  * @see ctdb_transaction_start_send
1212  *
1213  * @param[in] h Transaction handle
1214  * @param[in] key Record key
1215  * @param[in] mem_ctx Talloc memory context
1216  * @param[out] data Record data
1217  * @return 0 on success, errno on failure
1218  */
1219 int ctdb_transaction_fetch_record(struct ctdb_transaction_handle *h,
1220                                   TDB_DATA key,
1221                                   TALLOC_CTX *mem_ctx, TDB_DATA *data);
1222
1223 /**
1224  * @brief Store a record under a transaction
1225  *
1226  * @see ctdb_transaction_start_send
1227  *
1228  * @param[in] h Transaction handle
1229  * @param[in] key Record key
1230  * @param[in] data New record data
1231  * @return 0 on success, errno on failure
1232  */
1233 int ctdb_transaction_store_record(struct ctdb_transaction_handle *h,
1234                                   TDB_DATA key, TDB_DATA data);
1235
1236 /**
1237  * @brief Delete a record under a transaction
1238  *
1239  * @see ctdb_transaction_start_send
1240  *
1241  * @param[in] h Transaction handle
1242  * @param[in] key Record key
1243  * @return 0 on success, errno on failure
1244  */
1245 int ctdb_transaction_delete_record(struct ctdb_transaction_handle *h,
1246                                    TDB_DATA key);
1247
1248 /**
1249  * @brief Async computation start to commit a transaction
1250  *
1251  * @see ctdb_transaction_start_send
1252  *
1253  * @param[in] mem_ctx Talloc memory context
1254  * @param[in] ev Tevent context
1255  * @param[in] timeout How long to wait
1256  * @param[in] h Transaction handle
1257  * @return a new tevent req on success, NULL on failure
1258  */
1259 struct tevent_req *ctdb_transaction_commit_send(
1260                                         TALLOC_CTX *mem_ctx,
1261                                         struct tevent_context *ev,
1262                                         struct timeval timeout,
1263                                         struct ctdb_transaction_handle *h);
1264
1265 /**
1266  * @brief Async computation end to commit a transaction
1267  *
1268  * @param[in] req Tevent request
1269  * @param[out] perr errno in case of failure
1270  * @return true on success, false on failure
1271  */
1272 bool ctdb_transaction_commit_recv(struct tevent_req *req, int *perr);
1273
1274 /**
1275  * @brief Sync wrapper to commit a transaction
1276  *
1277  * @see ctdb_transaction_commit_send
1278  *
1279  * @param[in] h Transaction handle
1280  * @return 0 on success, errno on failure
1281  */
1282 int ctdb_transaction_commit(struct ctdb_transaction_handle *h);
1283
1284 /**
1285  * @brief Async computation start to cancel a transaction
1286  *
1287  * @see ctdb_transaction_start_send
1288  *
1289  * @param[in] mem_ctx Talloc memory context
1290  * @param[in] ev Tevent context
1291  * @param[in] timeout How long to wait
1292  * @param[in] h Transaction handle
1293  * @return a new tevent req on success, NULL on failure
1294  */
1295 struct tevent_req *ctdb_transaction_cancel_send(
1296                                         TALLOC_CTX *mem_ctx,
1297                                         struct tevent_context *ev,
1298                                         struct timeval timeout,
1299                                         struct ctdb_transaction_handle *h);
1300
1301 /**
1302  * @brief Async computation end to cancel a transaction
1303  *
1304  * @param[in] req Tevent request
1305  * @param[out] perr errno in case of failure
1306  * @return true on success, false on failure
1307  */
1308 bool ctdb_transaction_cancel_recv(struct tevent_req *req, int *perr);
1309
1310 /**
1311  * @brief Sync wrapper to cancel a transaction
1312  *
1313  * @see ctdb_transaction_cancel_send
1314  *
1315  * @param[in] h Transaction handle
1316  * @return 0 on success, errno on failure
1317  */
1318 int ctdb_transaction_cancel(struct ctdb_transaction_handle *h);
1319
1320 /**
1321  * @brief Utility function to extract a list of node ids from nodemap
1322  *
1323  * @param[in] nodemap Node map
1324  * @param[in] flags_mask Flags to match on
1325  * @param[in] exclude_pnn Node id to exclude from the list
1326  * @param[in] mem_ctx Talloc memory context
1327  * @param[out] pnn_list List of node ids
1328  * @return number of node ids on success, -1 on failure
1329  */
1330 int list_of_nodes(struct ctdb_node_map *nodemap,
1331                   uint32_t flags_mask, uint32_t exclude_pnn,
1332                   TALLOC_CTX *mem_ctx, uint32_t **pnn_list);
1333
1334 /**
1335  * @brief Utility function to extract a list of node ids for active nodes
1336  *
1337  * @param[in] nodemap Node map
1338  * @param[in] exclude_pnn Node id to exclude from the list
1339  * @param[in] mem_ctx Talloc memory context
1340  * @param[out] pnn_list List of node ids
1341  * @return number of node ids on success, -1 on failure
1342  */
1343 int list_of_active_nodes(struct ctdb_node_map *nodemap, uint32_t exclude_pnn,
1344                          TALLOC_CTX *mem_ctx, uint32_t **pnn_list);
1345
1346 /**
1347  * @brief Utility function to extract a list of node ids for connected nodes
1348  *
1349  * @param[in] nodemap Node map
1350  * @param[in] exclude_pnn Node id to exclude from the list
1351  * @param[in] mem_ctx Talloc memory context
1352  * @param[out] pnn_list List of node ids
1353  * @return number of node ids on success, -1 on failure
1354  */
1355 int list_of_connected_nodes(struct ctdb_node_map *nodemap,
1356                             uint32_t exclude_pnn,
1357                             TALLOC_CTX *mem_ctx, uint32_t **pnn_list);
1358
1359 /**
1360  * @brief Construct a new server id
1361  *
1362  * @param[in] client Client connection context
1363  * @param[in] task_id Task id
1364  * @return a new server id
1365  */
1366 struct ctdb_server_id ctdb_client_get_server_id(
1367                                 struct ctdb_client_context *client,
1368                                 uint32_t task_id);
1369
1370 /**
1371  * @brief Check if two server ids are the same
1372  *
1373  * @param[in] sid1 Server id 1
1374  * @param[in] sid2 Server id 2
1375  * @return true if the server ids are same, false otherwise
1376  */
1377 bool ctdb_server_id_equal(struct ctdb_server_id *sid1,
1378                           struct ctdb_server_id *sid2);
1379
1380 /**
1381  * @brief Check if the process with server id exists
1382  *
1383  * @param[in] mem_ctx Talloc memory context
1384  * @param[in] ev Tevent context
1385  * @param[in] client Client connection context
1386  * @param[in] sid Server id
1387  * @param[out] exists Boolean flag to indicate if the process exists
1388  * @return 0 on success, errno on failure
1389  */
1390 int ctdb_server_id_exists(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
1391                           struct ctdb_client_context *client,
1392                           struct ctdb_server_id *sid, bool *exists);
1393
1394 #endif /* __CTDB_CLIENT_H__ */