path: root/ctdb/client/client.h

/*
   CTDB client code

   Copyright (C) Amitay Isaacs  2015

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, see <http://www.gnu.org/licenses/>.
*/

#ifndef __CTDB_CLIENT_H__
#define __CTDB_CLIENT_H__

#include <talloc.h>
#include <tevent.h>

#include "protocol/protocol.h"
#include "common/srvid.h"

/**
 * @file client.h
 *
 * @brief Client api to talk to ctdb daemon
 *
 * This API allows one to connect to ctdb daemon, perform various database
 * operations, send controls to ctdb daemon and send messages to other ctdb
 * clients.
 */

/**
 * @brief The abstract context that holds client connection to ctdb daemon
 */
struct ctdb_client_context;

/**
 * @brief The abstract context that holds a tunnel endpoint
 */
struct ctdb_tunnel_context;

/**
 * @brief The abstract context that represents a clustered database
 */
struct ctdb_db_context;

/**
 * @brief The abstract context that represents a record from a distributed
 * database
 */
struct ctdb_record_handle;

/**
 * @brief The abstract context that represents a transaction on a replicated
 * database
 */
struct ctdb_transaction_handle;

/**
 * @brief Client callback function
 *
 * This function can be registered to be invoked in case of ctdb daemon going
 * away.
 */
typedef void (*ctdb_client_callback_func_t)(void *private_data);

/**
 * @brief Tunnel callback function
 *
 * This function is registered when a tunnel endpoint is set up.  When the
 * tunnel endpoint receives a message, this function is invoked.
 */
typedef void (*ctdb_tunnel_callback_func_t)(struct ctdb_tunnel_context *tctx,
					    uint32_t srcnode, uint32_t reqid,
					    uint8_t *buf, size_t buflen,
					    void *private_data);

/**
 * @brief Async computation start to initialize a connection to ctdb daemon
 *
 * This returns a ctdb client context.  Freeing this context will free the
 * connection to ctdb daemon and any memory associated with it.
 *
 * If the connection to ctdb daemon is lost, the client will terminate
 * automatically as the library will call exit().  If the client code
 * wants to perform cleanup or wants to re-establish a new connection,
 * the client should register a disconnect callback function.
 *
 * @see ctdb_client_set_disconnect_callback
 *
 * When a disconnect callback function is registered, client library will
 * not call exit().  It is the responsibility of the client code to take
 * appropriate action.
 *
 * @param[in] mem_ctx Talloc memory context
 * @param[in] ev Tevent context
 * @param[in] sockpath Path to ctdb daemon unix domain socket
 * @return new tevent request, NULL on failure
 */
struct tevent_req *ctdb_client_init_send(TALLOC_CTX *mem_ctx,
					 struct tevent_context *ev,
					 const char *sockpath);

/**
 * @brief Async computation end to initialize a connection to ctdb daemon
 *
 * @param[in] req Tevent request
 * @param[out] perr errno in case of failure
 * @param[in] mem_ctx Talloc memory context
 * @param[out] result The new ctdb client context
 * @return true on success, false on failure
 */
bool ctdb_client_init_recv(struct tevent_req *req, int *perr,
			   TALLOC_CTX *mem_ctx,
			   struct ctdb_client_context **result);

/**
 * @brief Sync wrapper to initialize ctdb connection
 *
 * @param[in] mem_ctx Talloc memory context
 * @param[in] ev Tevent context
 * @param[in] sockpath Path to ctdb daemon unix domain socket
 * @param[out] result The new ctdb client context
 * @return 0 on success, errno on failure
 */
int ctdb_client_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
		     const char *sockpath,
		     struct ctdb_client_context **result);

/**
 * @brief Register a callback in case of client disconnection
 *
 * This allows client code to know if the connection to ctdb daemon is lost.
 * This is useful if the client wants to re-establish a new connection to ctdb
 * daemon.
 *
 * @param[in] client Client connection context
 * @param[in] func Callback function
 * @param[in] private_data private data for callback function
 */
void ctdb_client_set_disconnect_callback(struct ctdb_client_context *client,
					 ctdb_client_callback_func_t func,
					 void *private_data);

/**
 * @brief Get the node number of the current node
 *
 * @param[in] client Client connection context
 * return node number on success, CTDB_UNKNOWN_PNN on error
 */
uint32_t ctdb_client_pnn(struct ctdb_client_context *client);

/**
 * @brief Client event loop waiting for a flag
 *
 * This can used to wait for asynchronous computations to complete.
 * When this function is called, it will run tevent event loop and wait
 * till the done flag is set to true.  This function will block and will
 * not return as long as the done flag is false.
 *
 * @param[in] ev Tevent context
 * @param[in] done Boolean flag to indicate when to stop waiting
 */
void ctdb_client_wait(struct tevent_context *ev, bool *done);

/**
 * @brief Client event loop waiting for function to return true with timeout
 *
 * This can be used to wait for asynchronous computations to complete.
 * When this function is called, it will run tevent event loop and wait
 * till the done function returns true or if the timeout occurs.
 *
 * This function will return when either
 *  - done function returns true, or
 *  - timeout has occurred.
 *
 * @param[in] ev Tevent context
 * @param[in] done_func Function flag to indicate when to stop waiting
 * @param[in] private_data Passed to done function
 * @param[in] timeout How long to wait
 * @return 0 on success, ETIMEDOUT on timeout, and errno on failure
 */
int ctdb_client_wait_func_timeout(struct tevent_context *ev,
				  bool (*done_func)(void *private_data),
				  void *private_data,
				  struct timeval timeout);

/**
 * @brief Client event loop waiting for a flag with timeout
 *
 * This can be used to wait for asynchronous computations to complete.
 * When this function is called, it will run tevent event loop and wait
 * till the done flag is set to true or if the timeout occurs.
 *
 * This function will return when either
 *  - done flag is set to true, or
 *  - timeout has occurred.
 *
 * @param[in] ev Tevent context
 * @param[in] done Boolean flag to indicate when to stop waiting
 * @param[in] timeout How long to wait
 * @return 0 on success, ETIMEDOUT on timeout, and errno on failure
 */
int ctdb_client_wait_timeout(struct tevent_context *ev, bool *done,
			     struct timeval timeout);

/**
 * @brief Async computation start to wait till recovery is completed
 *
 * CTDB daemon does not perform many operations while in recovery (especially
 * database operations).  This computation allows one to wait till ctdb daemon has
 * finished recovery.
 *
 * @param[in] mem_ctx Talloc memory context
 * @param[in] ev Tevent context
 * @param[in] client Client connection context
 * @return new tevent request, or NULL on failure
 */
struct tevent_req *ctdb_recovery_wait_send(TALLOC_CTX *mem_ctx,
					   struct tevent_context *ev,
					   struct ctdb_client_context *client);

/**
 * @brief Async computation end to wait till recovery is completed
 *
 * @param[in] req Tevent request
 * @param[out] perr errno in case of failure
 * @return true on success, false on failure
 */
bool ctdb_recovery_wait_recv(struct tevent_req *req, int *perr);

/**
 * @brief Sync wrapper for ctdb_recovery_wait computation
 *
 * @param[in] ev Tevent context
 * @param[in] client Client connection context
 * @return true on success, false on failure
 */
bool ctdb_recovery_wait(struct tevent_context *ev,
			struct ctdb_client_context *client);

/**
 * @brief Async computation start to migrate a database record
 *
 * This sends a request to ctdb daemon to migrate a database record to
 * the local node.  CTDB daemon will locate the data master for the record
 * and will migrate record (and the data master) to the current node.
 *
 * @see ctdb_fetch_lock_send
 *
 * @param[in] mem_ctx Talloc memory context
 * @param[in] ev  Tevent context
 * @param[in] client Client connection context
 * @param[in] request CTDB request data
 * @return a new tevent req, or NULL on failure
 */
struct tevent_req *ctdb_client_call_send(TALLOC_CTX *mem_ctx,
					 struct tevent_context *ev,
					 struct ctdb_client_context *client,
					 struct ctdb_req_call *request);

/**
 * @brief Async computation end to migrate a database record
 *
 * @param[in] req Tevent request
 * @param[in] mem_ctx Talloc memory context
 * @param[out] reply CTDB reply data
 * @param[out] perr errno in case of failure
 * @return true on success, false on failure
 */
bool ctdb_client_call_recv(struct tevent_req *req, TALLOC_CTX *mem_ctx,
			   struct ctdb_reply_call **reply, int *perr);


/**
 * @brief Async computation start to send a message to remote client(s)
 *
 * This sends a message to ctdb clients on a remote node.  All the
 * messages are associated with a specific SRVID.  All the clients on the
 * remote node listening to that SRVID, will get the message.
 *
 * Clients can register and deregister for messages for a SRVID using
 * ctdb_client_set_message_handler() and ctdb_client_remove_message_handler().
 *
 * @see ctdb_client_set_message_handler_send,
 *      ctdb_client_remove_message_handler_send
 *
 * @param[in] mem_ctx Talloc memory context
 * @param[in] ev Tevent context
 * @param[in] client Client connection context
 * @param[in] destnode Remote node id
 * @param[in] message Message to send
 * @return a new tevent req on success, NULL on failure
 */
struct tevent_req *ctdb_client_message_send(TALLOC_CTX *mem_ctx,
					    struct tevent_context *ev,
					    struct ctdb_client_context *client,
					    uint32_t destnode,
					    struct ctdb_req_message *message);

/**
 * @brief Async computation end to send a message to remote client(s)
 *
 * @param[in] req Tevent request
 * @param[out] perr errno in case of failure
 * @return true on success, false on failure
 */
bool ctdb_client_message_recv(struct tevent_req *req, int *perr);

/**
 * @brief Sync wrapper to send a message to client(s) on remote node
 *
 * @param[in] mem_ctx Talloc memory context
 * @param[in] ev Tevent context
 * @param[in] client Client connection context
 * @param[in] destnode Node id
 * @param[in] message Message to send
 */
int ctdb_client_message(T