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 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 represents a clustered database
  46  */
  47 struct ctdb_db_context;
  48
  49 /**
  50  * @brief The abstract context that represents a record from a distributed
  51  * database
  52  */
  53 struct ctdb_record_handle;
  54
  55 /**
  56  * @brief The abstract context that represents a transaction on a replicated
  57  * database
  58  */
  59 struct ctdb_transaction_handle;
  60
  61 /**
  62  * @brief Client callback function
  63  *
  64  * This function can be registered to be invoked in case of ctdb daemon going
  65  * away.
  66  */
  67 typedef void (*ctdb_client_callback_func_t)(void *private_data);
  68
  69 /**
  70  * @brief Initialize and connect to ctdb daemon
  71  *
  72  * This returns a ctdb client context.  Freeing this context will free the
  73  * connection to ctdb daemon and any memory associated with it.
  74  *
  75  * If the connection to ctdb daemon is lost, the client will terminate
  76  * automatically as the library will call exit().  If the client code
  77  * wants to perform cleanup or wants to re-establish a new connection,
  78  * the client should register a disconnect callback function.
  79  *
  80  * @see ctdb_client_set_disconnect_callback
  81  *
  82  * When a disconnect callback function is registered, client library will
  83  * not call exit().  It is the responsibility of the client code to take
  84  * appropriate action.
  85  *
  86  * @param[in] mem_ctx Talloc memory context
  87  * @param[in] ev Tevent context
  88  * @param[in] sockpath Path to ctdb daemon unix domain socket
  89  * @param[out] result The new ctdb client context
  90  * @return 0 on succcess, errno on failure
  91  */
  92 int ctdb_client_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
  93                      const char *sockpath,
  94                      struct ctdb_client_context **result);
  95
  96 /**
  97  * @brief Register a callback in case of client disconnection
  98  *
  99  * This allows client code to know if the connection to ctdb daemon is lost.
 100  * This is useful if the client wants to re-establish a new connection to ctdb
 101  * daemon.
 102  *
 103  * @param[in] client Client connection context
 104  * @param[in] func Callback function
 105  * @param[in] private_data private data for callback function
 106  */
 107 void ctdb_client_set_disconnect_callback(struct ctdb_client_context *client,
 108                                          ctdb_client_callback_func_t func,
 109                                          void *private_data);
 110
 111 /**
 112  * @brief Get the node number of the current node
 113  *
 114  * @param[in] client Client connection context
 115  * return node number on success, CTDB_UNKNOWN_PNN on error
 116  */
 117 uint32_t ctdb_client_pnn(struct ctdb_client_context *client);
 118
 119 /**
 120  * @brief Client event loop waiting for a flag
 121  *
 122  * This can used to wait for asynchronous comptuations to complete.
 123  * When this function is called, it will run tevent event loop and wait
 124  * till the done flag is set to true.  This function will block and will
 125  * not return as long as the done flag is false.
 126  *
 127  * @param[in] ev Tevent context
 128  * @param[in] done Boolean flag to indicate when to stop waiting
 129  */
 130 void ctdb_client_wait(struct tevent_context *ev, bool *done);
 131
 132 /**
 133  * @brief Client event loop waiting for a flag with timeout
 134  *
 135  * This can be used to wait for asynchronous computations to complete.
 136  * When this function is called, it will run tevent event loop and wait
 137  * till the done flag is set to true or if the timeout occurs.
 138  *
 139  * This function will return when either
 140  *  - done flag is set to true, or
 141  *  - timeout has occurred.
 142  *
 143  * @param[in] ev Tevent context
 144  * @param[in] done Boolean flag to indicate when to stop waiting
 145  * @param[in] timeout How long to wait
 146  * @return 0 on succes, ETIME on timeout, and errno on failure
 147  */
 148 int ctdb_client_wait_timeout(struct tevent_context *ev, bool *done,
 149                              struct timeval timeout);
 150
 151 /**
 152  * @brief Async computation start to wait till recovery is completed
 153  *
 154  * CTDB deamon does not perform many operations while in recovery (specially
 155  * database operations).  This computation allows to wait till ctdb daemon has
 156  * finished recovery.
 157  *
 158  * @param[in] mem_ctx Talloc memory context
 159  * @param[in] ev Tevent context
 160  * @param[in] client Client connection context
 161  * @return new tevent request, or NULL on failure
 162  */
 163 struct tevent_req *ctdb_recovery_wait_send(TALLOC_CTX *mem_ctx,
 164                                            struct tevent_context *ev,
 165                                            struct ctdb_client_context *client);
 166
 167 /**
 168  * @brief Async computation end to wait till recovery is completed
 169  *
 170  * @param[in] req Tevent request
 171  * @param[out] perr errno in case of failure
 172  * @return true on success, false on failure
 173  */
 174 bool ctdb_recovery_wait_recv(struct tevent_req *req, int *perr);
 175
 176 /**
 177  * @brief Sync wrapper for ctdb_recovery_wait computation
 178  *
 179  * @param[in] ev Tevent context
 180  * @param[in] client Client connection context
 181  * @return true on success, false on failure
 182  */
 183 bool ctdb_recovery_wait(struct tevent_context *ev,
 184                         struct ctdb_client_context *client);
 185
 186 /**
 187  * @brief Async computation start to migrate a database record
 188  *
 189  * This sends a request to ctdb daemon to migrate a database record to
 190  * the local node.  CTDB daemon will locate the data master for the record
 191  * and will migrate record (and the data master) to the current node.
 192  *
 193  * @see ctdb_fetch_lock_send
 194  *
 195  * @param[in] mem_ctx Talloc memory context
 196  * @param[in] ev  Tevent context
 197  * @param[in] client Client connection context
 198  * @param[in] request CTDB request data
 199  * @return a new tevent req, or NULL on failure
 200  */
 201 struct tevent_req *ctdb_client_call_send(TALLOC_CTX *mem_ctx,
 202                                          struct tevent_context *ev,
 203                                          struct ctdb_client_context *client,
 204                                          struct ctdb_req_call *request);
 205
 206 /**
 207  * @brief Async computation end to migrate a database record
 208  *
 209  * @param[in] req Tevent request
 210  * @param[in] mem_ctx Talloc memory context
 211  * @param[out] reply CTDB reply data
 212  * @param[out] perr errno in case of failure
 213  * @return true on success, false on failure
 214  */
 215 bool ctdb_client_call_recv(struct tevent_req *req, TALLOC_CTX *mem_ctx,
 216                            struct ctdb_reply_call **reply, int *perr);
 217
 218
 219 /**
 220  * @brief Async computation start to send a message to remote client(s)
 221  *
 222  * This sends a message to ctdb clients on a remote node.  All the
 223  * messages are associated with a specific SRVID.  All the clients on the
 224  * remote node listening to that SRVID, will get the message.
 225  *
 226  * Clients can register and deregister for messages for a SRVID using
 227  * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
 228  *
 229  * @see ctdb_client_set_message_handler_send,
 230  *      ctdb_client_remove_message_handler_send
 231  *
 232  * @param[in] mem_ctx Talloc memory context
 233  * @param[in] ev Tevent context
 234  * @param[in] client Client connection context
 235  * @param[in] destnode Remote node id
 236  * @param[in] message Message to send
 237  * @return a new tevent req on success, NULL on failure
 238  */
 239 struct tevent_req *ctdb_client_message_send(TALLOC_CTX *mem_ctx,
 240                                             struct tevent_context *ev,
 241                                             struct ctdb_client_context *client,
 242                                             uint32_t destnode,
 243                                             struct ctdb_req_message *message);
 244
 245 /**
 246  * @brief Async computation end to send a message to remote client(s)
 247  *
 248  * @param[in] req Tevent request
 249  * @param[out] perr errno in case of failure
 250  * @return true on success, false on failure
 251  */
 252 bool ctdb_client_message_recv(struct tevent_req *req, int *perr);
 253
 254 /**
 255  * @brief Sync wrapper to send a message to client(s) on remote node
 256  *
 257  * @param[in] mem_ctx Talloc memory context
 258  * @param[in] ev Tevent context
 259  * @param[in] client Client connection context
 260  * @param[in] destnode Node id
 261  * @param[in] message Message to send
 262  */
 263 int ctdb_client_message(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 264                         struct ctdb_client_context *client,
 265                         uint32_t destnode, struct ctdb_req_message *message);
 266
 267 /**
 268  * @brief Async computation start to send a message to multiple nodes
 269  *
 270  * This sends a message to ctdb clients on multiple remote nodes.  All the
 271  * messages are associated with a specific SRVID.  All the clients on remote
 272  * nodes listening to that SRVID, will get the message.
 273  *
 274  * Clients can register and deregister for messages for a SRVID using
 275  * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
 276  *
 277  * @see ctdb_client_set_message_handler_send,
 278  *      ctdb_client_remove_message_handler_send
 279  *
 280  * @param[in] mem_ctx Talloc memory context
 281  * @param[in] ev Tevent context
 282  * @param[in] client Client connection context
 283  * @param[in] pnn_list List of node ids
 284  * @param[in] count Number of node ids
 285  * @param[in] message Message to send
 286  * @return a new tevent req on success, NULL on failure
 287  */
 288 struct tevent_req *ctdb_client_message_multi_send(
 289                                 TALLOC_CTX *mem_ctx,
 290                                 struct tevent_context *ev,
 291                                 struct ctdb_client_context *client,
 292                                 uint32_t *pnn_list, int count,
 293                                 struct ctdb_req_message *message);
 294
 295 /**
 296  * @brief Async computation end to send a message to multiple nodes
 297  *
 298  * @param[in] req Tevent request
 299  * @param[out] perr errno in case of failure
 300  * @param[in] mem_ctx Talloc memory context
 301  * @param[out] perr_list The status from each node id
 302  * @return true on success, false on failure
 303  *
 304  * If perr_list is not NULL, then the status (0 on success, errno on failure)
 305  * of sending message to each of the node in the specified node list.  The
 306  * perr_list is an array of the same size as of pnn_list.
 307  */
 308 bool ctdb_client_message_multi_recv(struct tevent_req *req, int *perr,
 309                                     TALLOC_CTX *mem_ctx, int **perr_list);
 310
 311 /**
 312  * @brief Sync wrapper to send a message to multiple nodes
 313  *
 314  * @param[in] mem_ctx Talloc memory context
 315  * @param[in] ev Tevent context
 316  * @param[in] client Client connection context
 317  * @param[in] pnn_list List of node ids
 318  * @param[in] count Number of node ids
 319  * @param[in] message Message to send
 320  * @param[out] perr_list The status from each node id
 321  * @return 0 on success, errno on failure
 322  */
 323 int ctdb_client_message_multi(TALLOC_CTX *mem_ctx,
 324                               struct tevent_context *ev,
 325                               struct ctdb_client_context *client,
 326                               uint32_t *pnn_list, int count,
 327                               struct ctdb_req_message *message,
 328                               int **perr_list);
 329
 330 /**
 331  * @brief Async computation start to receive messages for a SRVID
 332  *
 333  * This computation informs ctdb that the client is interested in all messages
 334  * for a specific SRVID.
 335  *
 336  * @param[in] mem_ctx Talloc memory context
 337  * @param[in] ev Tevent context
 338  * @param[in] client Client connection context
 339  * @param[in] srvid SRVID
 340  * @param[in] handler Callback function to call when a message is received
 341  * @param[in] private_data Private data for callback
 342  * @return a new tevent req on success, NULL on failure
 343  */
 344 struct tevent_req *ctdb_client_set_message_handler_send(
 345                                         TALLOC_CTX *mem_ctx,
 346                                         struct tevent_context *ev,
 347                                         struct ctdb_client_context *client,
 348                                         uint64_t srvid,
 349                                         srvid_handler_fn handler,
 350                                         void *private_data);
 351
 352 /**
 353  * @brief Async computation end to receive messages for a SRVID
 354  *
 355  * @param[in] req Tevent request
 356  * @param[out] perr errno in case of failure
 357  * @return true on success, false on failure
 358  */
 359 bool ctdb_client_set_message_handler_recv(struct tevent_req *req, int *perr);
 360
 361 /**
 362  * Sync wrapper to receive messages for a SRVID
 363  *
 364  * @param[in] ev Tevent context
 365  * @param[in] client Client connection context
 366  * @param[in] srvid SRVID
 367  * @param[in] handler Callback function to call when a message is received
 368  * @param[in] private_data Private data for callback
 369  * @return 0 on success, errno on failure
 370  */
 371 int ctdb_client_set_message_handler(struct tevent_context *ev,
 372                                     struct ctdb_client_context *client,
 373                                     uint64_t srvid, srvid_handler_fn handler,
 374                                     void *private_data);
 375
 376 /**
 377  * @brief Async computation start to stop receiving messages for a SRVID
 378  *
 379  * This computation informs ctdb that the client is no longer interested in
 380  * messages for a specific SRVID.
 381  *
 382  * @param[in] mem_ctx Talloc memory context
 383  * @param[in] ev Tevent context
 384  * @param[in] client Client connection context
 385  * @param[in] srvid SRVID
 386  * @param[in] private_data Private data used to register callback
 387  * @return a new tevent req on success, NULL on failure
 388  */
 389 struct tevent_req *ctdb_client_remove_message_handler_send(
 390                                         TALLOC_CTX *mem_ctx,
 391                                         struct tevent_context *ev,
 392                                         struct ctdb_client_context *client,
 393                                         uint64_t srvid,
 394                                         void *private_data);
 395
 396 /**
 397  * @brief Async computation end to stop receiving messages for a SRVID
 398  *
 399  * @param[in] req Tevent request
 400  * @param[out] perr errno in case of failure
 401  * @return true on success, false on failure
 402  */
 403 bool ctdb_client_remove_message_handler_recv(struct tevent_req *req,
 404                                              int *perr);
 405
 406 /**
 407  * Sync wrapper to stop receiving messages for a SRVID
 408  *
 409  * @param[in] ev Tevent context
 410  * @param[in] client Client connection context
 411  * @param[in] srvid SRVID
 412  * @param[in] private_data Private data used to register callback
 413  * @return 0 on success, errno on failure
 414  */
 415 int ctdb_client_remove_message_handler(struct tevent_context *ev,
 416                                        struct ctdb_client_context *client,
 417                                        uint64_t srvid, void *private_data);
 418
 419 /**
 420  * @brief Async computation start to send a control to ctdb daemon
 421  *
 422  * @param[in] mem_ctx Talloc memory context
 423  * @param[in] ev Tevent context
 424  * @param[in] client Client connection context
 425  * @param[in] destnode Node id
 426  * @param[in] timeout How long to wait
 427  * @param[in] request Control request
 428  * @return a new tevent req on success, NULL on failure
 429  */
 430 struct tevent_req *ctdb_client_control_send(TALLOC_CTX *mem_ctx,
 431                                             struct tevent_context *ev,
 432                                             struct ctdb_client_context *client,
 433                                             uint32_t destnode,
 434                                             struct timeval timeout,
 435                                             struct ctdb_req_control *request);
 436
 437 /**
 438  * @brief Async computation end to send a control to ctdb daemon
 439  *
 440  * @param[in] req Tevent request
 441  * @param[out] perr errno in case of failure
 442  * @param[in] mem_ctx Talloc memory context
 443  * @param[out] preply Control reply
 444  * @return true on success, false on failure
 445  */
 446 bool ctdb_client_control_recv(struct tevent_req *req, int *perr,
 447                               TALLOC_CTX *mem_ctx,
 448                               struct ctdb_reply_control **preply);
 449
 450 /**
 451  * @brief Sync wrapper to send a control to ctdb daemon
 452  *
 453  * @param[in] mem_ctx Talloc memory context
 454  * @param[in] ev Tevent context
 455  * @param[in] client Client connection context
 456  * @param[in] destnode Node id
 457  * @param[in] timeout How long to wait
 458  * @param[in] request Control request
 459  * @param[out] preply Control reply
 460  * @return 0 on success, errno on failure
 461  */
 462 int ctdb_client_control(TALLOC_CTX *mem_ctx,
 463                         struct tevent_context *ev,
 464                         struct ctdb_client_context *client,
 465                         uint32_t destnode,
 466                         struct timeval timeout,
 467                         struct ctdb_req_control *request,
 468                         struct ctdb_reply_control **preply);
 469
 470 /**
 471  * @brief Async computation start to send a control to multiple nodes
 472  *
 473  * @param[in] mem_ctx Talloc memory context
 474  * @param[in] ev Tevent context
 475  * @param[in] client Client connection context
 476  * @param[in] pnn_list List of node ids
 477  * @param[in] count Number of node ids
 478  * @param[in] timeout How long to wait
 479  * @param[in] request Control request
 480  * @return a new tevent req on success, NULL on failure
 481  */
 482 struct tevent_req *ctdb_client_control_multi_send(
 483                                 TALLOC_CTX *mem_ctx,
 484                                 struct tevent_context *ev,
 485                                 struct ctdb_client_context *client,
 486                                 uint32_t *pnn_list, int count,
 487                                 struct timeval timeout,
 488                                 struct ctdb_req_control *request);
 489
 490 /**
 491  * @brief Async computation end to send a control to multiple nodes
 492  *
 493  * @param[in] req Tevent request
 494  * @param[out] perr errno in case of failure
 495  * @param[in] mem_ctx Talloc memory context
 496  * @param[out] perr_list Status from each node
 497  * @param[out] preply Control reply from each node
 498  * @return true on success, false on failure
 499  */
 500 bool ctdb_client_control_multi_recv(struct tevent_req *req, int *perr,
 501                                     TALLOC_CTX *mem_ctx, int **perr_list,
 502                                     struct ctdb_reply_control ***preply);
 503
 504 /**
 505  * @brief Sync wrapper to send a control to multiple nodes
 506  *
 507  * @param[in] mem_ctx Talloc memory context
 508  * @param[in] ev Tevent context
 509  * @param[in] client Client connection context
 510  * @param[in] pnn_list List of node ids
 511  * @param[in] count Number of node ids
 512  * @param[in] timeout How long to wait
 513  * @param[in] request Control request
 514  * @param[out] perr_list Status from each node
 515  * @param[out] preply Control reply from each node
 516  * @return 0 on success, errno on failure
 517  */
 518 int ctdb_client_control_multi(TALLOC_CTX *mem_ctx,
 519                               struct tevent_context *ev,
 520                               struct ctdb_client_context *client,
 521                               uint32_t *pnn_list, int count,
 522                               struct timeval timeout,
 523                               struct ctdb_req_control *request,
 524                               int **perr_list,
 525                               struct ctdb_reply_control ***preply);
 526
 527 /**
 528  * @brief Check err_list for errors
 529  *
 530  * This is a convenience function to parse the err_list returned from
 531  * functions that send requests to multiple nodes.
 532  *
 533  * If status from any of the node is non-zero, then return first non-zero
 534  * status.
 535  *
 536  * If status from all the nodes is 0, then return 0.
 537  *
 538  * @param[in] pnn_list List of node ids
 539  * @param[in] count Number of node ids
 540  * @param[in] err_list Status from each node
 541  * @param[out] pnn Node id in case of failure
 542  * @return 0 if no failures, status from first failure
 543  */
 544 int ctdb_client_control_multi_error(uint32_t *pnn_list, int count,
 545                                     int *err_list, uint32_t *pnn);
 546
 547 /**
 548  * @brief Async computation start to attach a database
 549  *
 550  * @param[in] mem_ctx Talloc memory context
 551  * @param[in] ev Tevent context
 552  * @param[in[ client Client connection context
 553  * @param[in] timeout How long to wait
 554  * @param[in] db_name Name of the database
 555  * @param[in] db_flags Database flags
 556  * @return a new tevent req on success, NULL on failure
 557  */
 558 struct tevent_req *ctdb_attach_send(TALLOC_CTX *mem_ctx,
 559                                     struct tevent_context *ev,
 560                                     struct ctdb_client_context *client,
 561                                     struct timeval timeout,
 562                                     const char *db_name, uint8_t db_flags);
 563
 564 /**
 565  * @brief Async computation end to attach a database
 566  *
 567  * @param[in] req Tevent request
 568  * @param[out] perr errno in case of failure
 569  * @param[out] result New database context
 570  * @return true on success, false on failure
 571  */
 572 bool ctdb_attach_recv(struct tevent_req *req, int *perr,
 573                       struct ctdb_db_context **result);
 574
 575 /**
 576  * @brief Sync wrapper to attach a database
 577  *
 578  * @param[in] ev Tevent context
 579  * @param[in[ client Client connection context
 580  * @param[in] timeout How long to wait
 581  * @param[in] db_name Name of the database
 582  * @param[in] db_flags Database flags
 583  * @param[out] result New database context
 584  * @return 0 on success, errno on failure
 585  */
 586 int ctdb_attach(struct tevent_context *ev,
 587                 struct ctdb_client_context *client,
 588                 struct timeval timeout,
 589                 const char *db_name, uint8_t db_flags,
 590                 struct ctdb_db_context **result);
 591
 592 /**
 593  * @brief Async computation start to detach a database
 594  *
 595  * Only volatile databases can be detached at runtime.
 596  *
 597  * @param[in] mem_ctx Talloc memory context
 598  * @param[in] ev Tevent context
 599  * @param[in[ client Client connection context
 600  * @param[in] timeout How long to wait
 601  * @param[in] db_id Database id
 602  * @return a new tevent req on success, NULL on failure
 603  */
 604 struct tevent_req *ctdb_detach_send(TALLOC_CTX *mem_ctx,
 605                                     struct tevent_context *ev,
 606                                     struct ctdb_client_context *client,
 607                                     struct timeval timeout, uint32_t db_id);
 608
 609 /**
 610  * @brief Async computation end to detach a database
 611  *
 612  * @param[in] req Tevent request
 613  * @param[out] perr errno in case of failure
 614  * @return true on success, false on failure
 615  */
 616 bool ctdb_detach_recv(struct tevent_req *req, int *perr);
 617
 618 /**
 619  * @brief Sync wrapper to detach a database
 620  *
 621  * Only volatile databases can be detached at runtime.
 622  *
 623  * @param[in] ev Tevent context
 624  * @param[in[ client Client connection context
 625  * @param[in] timeout How long to wait
 626  * @param[in] db_id Database id
 627  * @return 0 on success, errno on failure
 628  */
 629 int ctdb_detach(struct tevent_context *ev,
 630                 struct ctdb_client_context *client,
 631                 struct timeval timeout, uint32_t db_id);
 632
 633
 634 /**
 635  * @brief Get database id from database context
 636  *
 637  * @param[in] db Database context
 638  * @return database id
 639  */
 640 uint32_t ctdb_db_id(struct ctdb_db_context *db);
 641
 642 /**
 643  * @brief Traverse a database locally on the node
 644  *
 645  * This function traverses a database locally on the node and for each record
 646  * calls the parser function.  If the parser function returns 1, the traverse
 647  * will terminate.  If parser function returns 0, the traverse will continue
 648  * till all records in database are parsed.
 649  *
 650  * This is useful for replicated databases, since each node has exactly the
 651  * same records.
 652  *
 653  * @param[in] db Database context
 654  * @param[in] readonly Is the traversal for reading or updating
 655  * @param[in] extract_header Whether to extract ltdb header from record data
 656  * @param[in] parser Record parsing function
 657  * @param[in] private_data Private data for parser function
 658  * @return 0 on success, non-zero return value from parser function
 659  */
 660 int ctdb_db_traverse_local(struct ctdb_db_context *db, bool readonly,
 661                            bool extract_header,
 662                            ctdb_rec_parser_func_t parser, void *private_data);
 663
 664 /**
 665  * @brief Async computation start to a cluster-wide database traverse
 666  *
 667  * This function traverses a database on all the nodes and for each record
 668  * calls the parser function.  If the parser function returns 1, the traverse
 669  * will terminate.  If parser function returns 0, the traverse will continue
 670  * till all records all on nodes are parsed.
 671  *
 672  * This is useful for distributed databases as the records are distributed
 673  * among the cluster nodes.
 674  *
 675  * @param[in] mem_ctx Talloc memory context
 676  * @param[in] ev Tevent context
 677  * @param[in] client Client connection context
 678  * @param[in] db Database context
 679  * @param[in] destnode Node id
 680  * @param[in] timeout How long to wait
 681  * @param[in] parser Record parser function
 682  * @param[in] private_data Private data for parser
 683  * @return a new tevent req on success, NULL on failure
 684  */
 685 struct tevent_req *ctdb_db_traverse_send(TALLOC_CTX *mem_ctx,
 686                                          struct tevent_context *ev,
 687                                          struct ctdb_client_context *client,
 688                                          struct ctdb_db_context *db,
 689                                          uint32_t destnode,
 690                                          struct timeval timeout,
 691                                          ctdb_rec_parser_func_t parser,
 692                                          void *private_data);
 693
 694 /**
 695  * @brief Async computation end to a cluster-wide database traverse
 696  *
 697  * @param[in] req Tevent request
 698  * @param[out] perr errno in case of failure
 699  * @return true on success, false on failure
 700  */
 701 bool ctdb_db_traverse_recv(struct tevent_req *req, int *perr);
 702
 703 /**
 704  * @brief Sync wrapper for a cluster-wide database traverse
 705  *
 706  * @param[in] mem_ctx Talloc memory context
 707  * @param[in] ev Tevent context
 708  * @param[in] client Client connection context
 709  * @param[in] db Database context
 710  * @param[in] destnode Node id
 711  * @param[in] timeout How long to wait
 712  * @param[in] parser Record parser function
 713  * @param[in] private_data Private data for parser
 714  * @return 0 on success, errno on failure or non-zero status from parser
 715  */
 716 int ctdb_db_traverse(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 717                      struct ctdb_client_context *client,
 718                      struct ctdb_db_context *db,
 719                      uint32_t destnode, struct timeval timeout,
 720                      ctdb_rec_parser_func_t parser, void *private_data);
 721
 722 /**
 723  * @brief Fetch a record from a local database
 724  *
 725  * This function is primarily for internal use.
 726  * Clients should use ctdb_fetch_lock() instead.
 727  *
 728  * @param[in] db Database context
 729  * @param[in] key Record key
 730  * @param[out] header Record header
 731  * @param[in] mem_ctx Talloc memory context
 732  * @param[out] data Record data
 733  */
 734 int ctdb_ltdb_fetch(struct ctdb_db_context *db, TDB_DATA key,
 735                     struct ctdb_ltdb_header *header,
 736                     TALLOC_CTX *mem_ctx, TDB_DATA *data);
 737
 738 /**
 739  * @brief Async computation start to fetch a locked record
 740  *
 741  * This function is used to fetch a record from a distributed database.
 742  *
 743  * If the record is already available on the local node, then lock the
 744  * record and return the record handle.
 745  *
 746  * If the record is not available on the local node, send a CTDB request to
 747  * migrate the record.  Once the record is migrated to the local node, lock
 748  * the record and return the record handle.
 749  *
 750  * At the end of the computation, a record handle is returned which holds
 751  * the record lock.  When the record handle is freed, the record is unlocked.
 752  *
 753  * @param[in] mem_ctx Talloc memory context
 754  * @param[in] ev Tevent context
 755  * @param[in] client Client context
 756  * @param[in] db Database context
 757  * @param[in] key Record key
 758  * @param[in] readonly Whether to request readonly copy of the record
 759  * @return a new tevent req on success, NULL on failure
 760  */
 761 struct tevent_req *ctdb_fetch_lock_send(TALLOC_CTX *mem_ctx,
 762                                         struct tevent_context *ev,
 763                                         struct ctdb_client_context *client,
 764                                         struct ctdb_db_context *db,
 765                                         TDB_DATA key, bool readonly);
 766
 767 /**
 768  * @brief Async computation end to fetch a locked record
 769  *
 770  * @param[in] req Tevent request
 771  * @param[out] header Record header
 772  * @param[in] mem_ctx Talloc memory context
 773  * @param[out] data Record data
 774  * @param[out] perr errno in case of failure
 775  * @return a new record handle, NULL on failure
 776  */
 777 struct ctdb_record_handle *ctdb_fetch_lock_recv(struct tevent_req *req,
 778                                                 struct ctdb_ltdb_header *header,
 779                                                 TALLOC_CTX *mem_ctx,
 780                                                 TDB_DATA *data, int *perr);
 781
 782 /**
 783  * @brief Sync wrapper to fetch a locked record
 784  *
 785  * @see ctdb_fetch_lock_send
 786  *
 787  * @param[in] mem_ctx Talloc memory context
 788  * @param[in] ev Tevent context
 789  * @param[in] client Client context
 790  * @param[in] db Database context
 791  * @param[in] key Record key
 792  * @param[in] readonly Whether to request readonly copy of the record
 793  * @param[out] header Record header
 794  * @param[out] data Record data
 795  * return 0 on success, errno on failure
 796  */
 797 int ctdb_fetch_lock(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 798                     struct ctdb_client_context *client,
 799                     struct ctdb_db_context *db, TDB_DATA key, bool readonly,
 800                     struct ctdb_record_handle **out,
 801                     struct ctdb_ltdb_header *header, TDB_DATA *data);
 802
 803 /**
 804  * @brief Update a locked record
 805  *
 806  * This function is used to update a record in a distributed database.
 807  *
 808  * This function should NOT be used to store null data, instead use
 809  * ctdb_delete_record().
 810  *
 811  * @param[in] h Record handle
 812  * @param[in] data New record data
 813  * @return 0 on success, errno on failure
 814  */
 815 int ctdb_store_record(struct ctdb_record_handle *h, TDB_DATA data);
 816
 817 /**
 818  * @brief Async computation start to delete a locked record
 819  *
 820  * This function is used to delete a record in a distributed database
 821  *
 822  * @param[in] mem_ctx Talloc memory context
 823  * @param[in] ev Tevent context
 824  * @param[in] h Record handle
 825  * @return a new tevent req on success, NULL on failure
 826  */
 827 struct tevent_req *ctdb_delete_record_send(TALLOC_CTX *mem_ctx,
 828                                            struct tevent_context *ev,
 829                                            struct ctdb_record_handle *h);
 830
 831 /**
 832  * @brief Async computation end to delete a locked record
 833  *
 834  * @param[in] req Tevent request
 835  * @param[out] perr errno in case of failure
 836  * @return true on success, false on failure
 837  */
 838 bool ctdb_delete_record_recv(struct tevent_req *req, int *perr);
 839
 840 /**
 841  * @brief Sync wrapper to delete a locked record
 842  *
 843  * @see ctdb_delete_record_send
 844  *
 845  * @param[in] h Record handle
 846  * @return 0 on success, errno on failure
 847  */
 848 int ctdb_delete_record(struct ctdb_record_handle *h);
 849
 850 /**
 851  * @brief Async computation start to get a global database lock
 852  *
 853  * Functions related to global locks are primarily used internally for
 854  * implementing transaction api.
 855  *
 856  * Clients should use transaction api directly.
 857  * @see ctdb_transaction_start_send
 858  *
 859  * @param[in] mem_ctx Talloc memory context
 860  * @param[in] ev Tevent context
 861  * @param[in] client Client context
 862  * @param[in] db Database context for g_lock.tdb
 863  * @param[in] keyname Record key
 864  * @param[in] sid Server id
 865  * @param[in] readonly Lock type
 866  * @return a new tevent req on success, NULL on failure
 867  */
 868 struct tevent_req *ctdb_g_lock_lock_send(TALLOC_CTX *mem_ctx,
 869                                          struct tevent_context *ev,
 870                                          struct ctdb_client_context *client,
 871                                          struct ctdb_db_context *db,
 872                                          const char *keyname,
 873                                          struct ctdb_server_id *sid,
 874                                          bool readonly);
 875
 876 /**
 877  * @brief Async computation end to get a global database lock
 878  *
 879  * @param[in] req Tevent request
 880  * @param[out] perr errno in case of failure
 881  * @return true on success, false on failure
 882  */
 883 bool ctdb_g_lock_lock_recv(struct tevent_req *req, int *perr);
 884
 885 /**
 886  * @brief Async computation start to release a global database lock
 887  *
 888  * @param[in] mem_ctx Talloc memory context
 889  * @param[in] ev Tevent context
 890  * @param[in] client Client connection context
 891  * @param[in] db Database context
 892  * @param[in] keyname Record key
 893  * @param[in] sid Server id
 894  * @return a new tevent req on success, NULL on failure
 895  */
 896 struct tevent_req *ctdb_g_lock_unlock_send(TALLOC_CTX *mem_ctx,
 897                                            struct tevent_context *ev,
 898                                            struct ctdb_client_context *client,
 899                                            struct ctdb_db_context *db,
 900                                            const char *keyname,
 901                                            struct ctdb_server_id sid);
 902
 903 /**
 904  * @brief Async computation end to release a global database lock
 905  *
 906  * @param[in] req Tevent request
 907  * @param[out] perr errno in case of failure
 908  * @return true on success, false on failure
 909  */
 910 bool ctdb_g_lock_unlock_recv(struct tevent_req *req, int *perr);
 911
 912 /**
 913  * @brief Async computation start to start a transaction
 914  *
 915  * This function is used to start a transaction on a replicated database.
 916  *
 917  * To perform any updates on a replicated database
 918  * - start transaction
 919  * - fetch record (ctdb_transaction_fetch_record)
 920  * - store record (ctdb_transaction_store_record)
 921  * - delete record (ctdb_transaction_delete_record)
 922  * - commit transaction (ctdb_transaction_commit_send), or
 923  * - cancel transaction (ctdb_transaction_cancel_send)
 924  *
 925  * Starting a transaction will return a transaction handle.  This is used
 926  * for updating records under a transaction.  This handle is automatically
 927  * freed once the transacion is committed or cancelled.
 928  *
 929  * Clients should NOT free the transaction handle.
 930  *
 931  * @param[in] mem_ctx Talloc memory context
 932  * @param[in] ev Tevent context
 933  * @param[in] client Client connection context
 934  * @param[in] timeout How long to wait
 935  * @param[in] db Database context
 936  * @param[in] readonly Is transaction readonly
 937  * @return a new tevent req on success, NULL on failure
 938  */
 939 struct tevent_req *ctdb_transaction_start_send(TALLOC_CTX *mem_ctx,
 940                                                struct tevent_context *ev,
 941                                                struct ctdb_client_context *client,
 942                                                struct timeval timeout,
 943                                                struct ctdb_db_context *db,
 944                                                bool readonly);
 945
 946 /**
 947  * @brief Async computation end to start a transaction
 948  *
 949  * @param[in] req Tevent request
 950  * @param[out] perr errno in case of failure
 951  * @return a new transaction handle on success, NULL on failure
 952  */
 953 struct ctdb_transaction_handle *ctdb_transaction_start_recv(
 954                                         struct tevent_req *req,
 955                                         int *perr);
 956
 957 /**
 958  * @brief Sync wrapper to start a transaction
 959  *
 960  * @see ctdb_transaction_start_send
 961  *
 962  * @param[in] mem_ctx Talloc memory context
 963  * @param[in] ev Tevent context
 964  * @param[in] client Client connection context
 965  * @param[in] timeout How long to wait
 966  * @param[in] db Database context
 967  * @param[in] readonly Is transaction readonly
 968  * @param[out] result a new transaction handle
 969  * @return 0 on success, errno on failure
 970  */
 971 int ctdb_transaction_start(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
 972                            struct ctdb_client_context *client,
 973                            struct timeval timeout,
 974                            struct ctdb_db_context *db, bool readonly,
 975                            struct ctdb_transaction_handle **result);
 976
 977 /**
 978  * @brief Fetch a record under a transaction
 979  *
 980  * @see ctdb_transaction_start_send
 981  *
 982  * @param[in] h Transaction handle
 983  * @param[in] key Record key
 984  * @param[in] mem_ctx Talloc memory context
 985  * @param[out] data Record data
 986  * @return 0 on success, errno on failure
 987  */
 988 int ctdb_transaction_fetch_record(struct ctdb_transaction_handle *h,
 989                                   TDB_DATA key,
 990                                   TALLOC_CTX *mem_ctx, TDB_DATA *data);
 991
 992 /**
 993  * @brief Store a record under a transaction
 994  *
 995  * @see ctdb_transaction_start_send
 996  *
 997  * @param[in] h Transaction handle
 998  * @param[in] key Record key
 999  * @param[in] data New record data
1000  * @return 0 on success, errno on failure
1001  */
1002 int ctdb_transaction_store_record(struct ctdb_transaction_handle *h,
1003                                   TDB_DATA key, TDB_DATA data);
1004
1005 /**
1006  * @brief Delete a record under a transaction
1007  *
1008  * @see ctdb_transaction_start_send
1009  *
1010  * @param[in] h Transaction handle
1011  * @param[in] key Record key
1012  * @return 0 on success, errno on failure
1013  */
1014 int ctdb_transaction_delete_record(struct ctdb_transaction_handle *h,
1015                                    TDB_DATA key);
1016
1017 /**
1018  * @brief Async computation start to commit a transaction
1019  *
1020  * @see ctdb_transaction_start_send
1021  *
1022  * @param[in] mem_ctx Talloc memory context
1023  * @param[in] ev Tevent context
1024  * @param[in] timeout How long to wait
1025  * @param[in] h Transaction handle
1026  * @return a new tevent req on success, NULL on failure
1027  */
1028 struct tevent_req *ctdb_transaction_commit_send(
1029                                         TALLOC_CTX *mem_ctx,
1030                                         struct tevent_context *ev,
1031                                         struct timeval timeout,
1032                                         struct ctdb_transaction_handle *h);
1033
1034 /**
1035  * @brief Async computation end to commit a transaction
1036  *
1037  * @param[in] req Tevent request
1038  * @param[out] perr errno in case of failure
1039  * @return true on success, false on failure
1040  */
1041 bool ctdb_transaction_commit_recv(struct tevent_req *req, int *perr);
1042
1043 /**
1044  * @brief Sync wrapper to commit a transaction
1045  *
1046  * @see ctdb_transaction_commit_send
1047  *
1048  * @param[in] h Transaction handle
1049  * @return 0 on success, errno on failure
1050  */
1051 int ctdb_transaction_commit(struct ctdb_transaction_handle *h);
1052
1053 /**
1054  * @brief Async computation start to cancel a transaction
1055  *
1056  * @see ctdb_transaction_start_send
1057  *
1058  * @param[in] mem_ctx Talloc memory context
1059  * @param[in] ev Tevent context
1060  * @param[in] timeout How long to wait
1061  * @param[in] h Transaction handle
1062  * @return a new tevent req on success, NULL on failure
1063  */
1064 struct tevent_req *ctdb_transaction_cancel_send(
1065                                         TALLOC_CTX *mem_ctx,
1066                                         struct tevent_context *ev,
1067                                         struct timeval timeout,
1068                                         struct ctdb_transaction_handle *h);
1069
1070 /**
1071  * @brief Async computation end to cancel a transaction
1072  *
1073  * @param[in] req Tevent request
1074  * @param[out] perr errno in case of failure
1075  * @return true on success, false on failure
1076  */
1077 bool ctdb_transaction_cancel_recv(struct tevent_req *req, int *perr);
1078
1079 /**
1080  * @brief Sync wrapper to cancel a transaction
1081  *
1082  * @see ctdb_transaction_cancel_send
1083  *
1084  * @param[in] h Transaction handle
1085  * @return 0 on success, errno on failure
1086  */
1087 int ctdb_transaction_cancel(struct ctdb_transaction_handle *h);
1088
1089 /**
1090  * @brief Utility function to extract a list of node ids from nodemap
1091  *
1092  * @param[in] nodemap Node map
1093  * @param[in] flags_mask Flags to match on
1094  * @param[in] exclude_pnn Node id to exclude from the list
1095  * @param[in] mem_ctx Talloc memory context
1096  * @param[out] pnn_list List of node ids
1097  * @return number of node ids on success, -1 on failure
1098  */
1099 int list_of_nodes(struct ctdb_node_map *nodemap,
1100                   uint32_t flags_mask, uint32_t exclude_pnn,
1101                   TALLOC_CTX *mem_ctx, uint32_t **pnn_list);
1102
1103 /**
1104  * @brief Utility function to extract a list of node ids for active nodes
1105  *
1106  * @param[in] nodemap Node map
1107  * @param[in] exclude_pnn Node id to exclude from the list
1108  * @param[in] mem_ctx Talloc memory context
1109  * @param[out] pnn_list List of node ids
1110  * @return number of node ids on success, -1 on failure
1111  */
1112 int list_of_active_nodes(struct ctdb_node_map *nodemap, uint32_t exclude_pnn,
1113                          TALLOC_CTX *mem_ctx, uint32_t **pnn_list);
1114
1115 /**
1116  * @brief Utility function to extract a list of node ids for connected nodes
1117  *
1118  * @param[in] nodemap Node map
1119  * @param[in] exclude_pnn Node id to exclude from the list
1120  * @param[in] mem_ctx Talloc memory context
1121  * @param[out] pnn_list List of node ids
1122  * @return number of node ids on success, -1 on failure
1123  */
1124 int list_of_connected_nodes(struct ctdb_node_map *nodemap,
1125                             uint32_t exclude_pnn,
1126                             TALLOC_CTX *mem_ctx, uint32_t **pnn_list);
1127
1128 /**
1129  * @brief Construct a new server id
1130  *
1131  * @param[in] client Client connection context
1132  * @param[in] task_id Task id
1133  * @return a new server id
1134  */
1135 struct ctdb_server_id ctdb_client_get_server_id(
1136                                 struct ctdb_client_context *client,
1137                                 uint32_t task_id);
1138
1139 /**
1140  * @brief Check if two server ids are the same
1141  *
1142  * @param[in] sid1 Server id 1
1143  * @param[in] sid2 Server id 2
1144  * @return true if the server ids are same, false otherwise
1145  */
1146 bool ctdb_server_id_equal(struct ctdb_server_id *sid1,
1147                           struct ctdb_server_id *sid2);
1148
1149 /**
1150  * @brief Check if the process with server id exists
1151  *
1152  * @param[in] mem_ctx Talloc memory context
1153  * @param[in] ev Tevent context
1154  * @param[in] client Client connection context
1155  * @param[in] sid Server id
1156  * @param[out] exists Boolean flag to indicate if the process exists
1157  * @return 0 on success, errno on failure
1158  */
1159 int ctdb_server_id_exists(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
1160                           struct ctdb_client_context *client,
1161                           struct ctdb_server_id *sid, bool *exists);
1162
1163 #endif /* __CTDB_CLIENT_H__ */