[SCM] CTDB repository - branch master updated - ctdb-1.0.114-139-g8fec60c
Ronnie Sahlberg
sahlberg at samba.org
Fri Jun 4 22:40:21 MDT 2010
The branch, master has been updated
via 8fec60cb92d26886d853c918b8bc7931fec46469 (commit)
via 9ec0b9bb148327a40e439d9c643c9d2ff93ce598 (commit)
via ced3bc40f841d353bc86a6ee9dd1868473223f52 (commit)
via 108e9c2450876a9f8821aa7efd5be971eee5afd3 (commit)
via cdc19dc73032470d57f38bf825d8113b3a0c8cd1 (commit)
via e285b5d5a9d4fbc4f75dbb237d2fcdbd84f2d605 (commit)
via c620cfbad3b5f0d6330ef47f572d4ade08e169e8 (commit)
via fecb8a19e97f6e453066461b234acdb0946bbadd (commit)
via 86259aa395555aaf7b2fae7326caa2ea62961092 (commit)
via 0786152472bc43efae4c896f7c6c07c6e080b9b2 (commit)
from 87dc18a3a051da04685f14529c53c428d37c2912 (commit)
http://gitweb.samba.org/?p=sahlberg/ctdb.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit 8fec60cb92d26886d853c918b8bc7931fec46469
Author: Ronnie Sahlberg <ronniesahlberg at gmail.com>
Date: Sat Jun 5 14:38:01 2010 +1000
update "ctdb pnn" to use the new return value for _recv() where
bool false means failure and true means success.
commit 9ec0b9bb148327a40e439d9c643c9d2ff93ce598
Author: Ronnie Sahlberg <ronniesahlberg at gmail.com>
Date: Sat Jun 5 14:27:46 2010 +1000
Must initialize ctdb->locks or else bad things happen
commit ced3bc40f841d353bc86a6ee9dd1868473223f52
Author: Ronnie Sahlberg <ronniesahlberg at gmail.com>
Date: Sat Jun 5 14:21:42 2010 +1000
Update the ctdb tool to use the new signature for ctdb_connect()
commit 108e9c2450876a9f8821aa7efd5be971eee5afd3
Author: Rusty Russell <rusty at rustcorp.com.au>
Date: Fri Jun 4 20:30:08 2010 +0930
libctdb: documentation
Full documentation for all the functions.
This looks longer than it is, because it sorts them into async and
sync parts, and also renames some formal parameters.
Added TODO to libctdb directory to track our plans.
Signed-off-by: Rusty Russell <rusty at rustcorp.com.au>
commit cdc19dc73032470d57f38bf825d8113b3a0c8cd1
Author: Rusty Russell <rusty at rustcorp.com.au>
Date: Fri Jun 4 20:22:03 2010 +0930
libctdb: use values from ctdb_protocol.h, don't re-declare
We're best off including ctdb_protocol.h to get these, even if we
document the important ones in ctdb.h.
Signed-off-by: Rusty Russell <rusty at rustcorp.com.au>
commit e285b5d5a9d4fbc4f75dbb237d2fcdbd84f2d605
Author: Rusty Russell <rusty at rustcorp.com.au>
Date: Fri Jun 4 20:19:25 2010 +0930
libctdb: use bool in API
Return bool instead of -1/0; that's what the young kids are doing
these days!
Signed-off-by: Rusty Russell <rusty at rustcorp.com.au>
commit c620cfbad3b5f0d6330ef47f572d4ade08e169e8
Author: Rusty Russell <rusty at rustcorp.com.au>
Date: Fri Jun 4 19:41:42 2010 +0930
libctdb: track lock for each ctdb_db, complain if they hold too long.
In particular, this stops them grabbing two (with wrappers so we can
enhance this logic once we support threads), and warns them if they
re-enter ctdb_service() holding a lock (you are not supposed to block!).
Signed-off-by: Rusty Russell <rusty at rustcorp.com.au>
commit fecb8a19e97f6e453066461b234acdb0946bbadd
Author: Rusty Russell <rusty at rustcorp.com.au>
Date: Fri Jun 4 20:27:06 2010 +0930
patch libctdb-use-logging.patch
commit 86259aa395555aaf7b2fae7326caa2ea62961092
Author: Rusty Russell <rusty at rustcorp.com.au>
Date: Fri Jun 4 20:27:03 2010 +0930
libctdb: add logging infrastructure
This is based on Ronnie's work, merged with mine. That means
errors are all my fault.
Differences from Ronnie's:
1) use syslog's LOG_ levels directly.
2) typesafe arg to log function, and use it (eg stderr) in helper function.
3) store fn in ctdb context, and expose ctdb_log_level directly thru API.
Signed-off-by: Rusty Russell <rusty at rustcorp.com.au>
commit 0786152472bc43efae4c896f7c6c07c6e080b9b2
Author: Rusty Russell <rusty at rustcorp.com.au>
Date: Fri Jun 4 16:54:08 2010 +0930
libctdb: add ctdb arg to more functions.
This is going to help for logging, since we want it there.
Signed-off-by: Rusty Russell <rusty at rustcorp.com.au>
-----------------------------------------------------------------------
Summary of changes:
Makefile.in | 3 +-
include/ctdb.h | 522 +++++++++++++++++++++++++++++++++++----------
libctdb/TODO | 3 +
libctdb/control.c | 32 ++-
libctdb/ctdb.c | 252 ++++++++++++++++------
libctdb/libctdb_private.h | 25 ++-
libctdb/logging.c | 56 +++++
libctdb/messages.c | 42 +++-
libctdb/sync.c | 56 +++---
libctdb/tst.c | 39 ++--
tools/ctdb.c | 7 +-
11 files changed, 783 insertions(+), 254 deletions(-)
create mode 100644 libctdb/TODO
create mode 100644 libctdb/logging.c
Changeset truncated at 500 lines:
diff --git a/Makefile.in b/Makefile.in
index dd7864e..d2e0dea 100755
--- a/Makefile.in
+++ b/Makefile.in
@@ -47,7 +47,8 @@ CTDB_COMMON_OBJ = common/ctdb_io.o common/ctdb_util.o \
common/ctdb_logging.c
CTDB_LIB_OBJ = libctdb/ctdb.o libctdb/io_elem.o libctdb/local_tdb.o \
- libctdb/messages.o libctdb/sync.o libctdb/control.o
+ libctdb/messages.o libctdb/sync.o libctdb/control.o \
+ libctdb/logging.o
CTDB_TCP_OBJ = tcp/tcp_connect.o tcp/tcp_io.o tcp/tcp_init.o
diff --git a/include/ctdb.h b/include/ctdb.h
index fa3f30d..e62bb45 100644
--- a/include/ctdb.h
+++ b/include/ctdb.h
@@ -23,191 +23,490 @@
#include <sys/types.h>
#include <stdint.h>
#include <stdbool.h>
+#include <stdarg.h>
+#include <stdio.h>
#include <tdb.h>
+#include <ctdb_protocol.h>
-/* All *_send() functions are guaranteed to be non-blocking and fully
- * asynchronous. The non-_send variants are synchronous.
+/**
+ * ctdb - a library for accessing tdbs controlled by ctdbd
+ *
+ * ctdbd (clustered tdb daemon) is a daemon designed to syncronize TDB
+ * databases across a cluster. Using this library, you can communicate with
+ * the daemon to access the databases, pass messages across the cluster, and
+ * control the daemon itself.
+ *
+ * The general API is event-driven and asynchronous: you call the
+ * *_send functions, supplying callbacks, then when the ctdbd file
+ * descriptor is usable, call ctdb_service() to perform read from it
+ * and call your callbacks, which use the *_recv functions to unpack
+ * the replies from ctdbd.
+ *
+ * There is also a synchronous wrapper for each function for trivial
+ * programs; these can be found in the section marked "Synchronous API".
*/
-/*
- * Connect to ctdb using the specified domain socket.
- * Returns a ctdb context if successful or NULL.
+typedef void (*ctdb_log_fn_t)(void *log_priv,
+ int severity, const char *format, va_list ap);
+
+/**
+ * ctdb_connect - connect to ctdb using the specified domain socket.
+ * @addr: the socket address, or NULL for default
+ * @log: the logging function
+ * @log_priv: the private argument to the logging function.
+ *
+ * Returns a ctdb context if successful or NULL. Use ctdb_free() to
+ * release the returned ctdb_connection when finished.
+ *
+ * The log() function can be typesafe: the log_priv arg and signature
+ * of log() should match. The priority passed to log() os as per
+ * syslog(3).
+ *
+ * See Also:
+ * ctdb_log_file()
+ */
+struct ctdb_connection *ctdb_connect(const char *addr,
+ ctdb_log_fn_t log_fn, void *log_priv);
+
+/**
+ * ctdb_log_file - example logging function
+ *
+ * Logs everything at priority LOG_WARNING or above to the file given (via
+ * the log_priv argument, usually stderr).
+ */
+void ctdb_log_file(FILE *, int, const char *, va_list);
+
+/**
+ * ctdb_log_level - level at which to call logging function
+ *
+ * This variable globally controls filtering on the logging function.
+ * It is initialized to LOG_WARNING, meaning that strange but nonfatal
+ * events, as well as errors and API misuses are reported.
*
+ * Set it to LOG_DEBUG to receive all messages.
*/
-struct ctdb_connection *ctdb_connect(const char *addr);
+extern int ctdb_log_level;
+
+/***
+ *
+ * Asynchronous API
+ *
+ ***/
+/**
+ * ctdb_get_fd - get the filedescriptor to select/poll on
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ *
+ * By using poll or select on this file descriptor, you will know when to call
+ * ctdb_service().
+ *
+ * See Also:
+ * ctdb_which_events(), ctdb_service()
+ */
int ctdb_get_fd(struct ctdb_connection *ctdb);
+/**
+ * ctdb_which_events - determine which events ctdb_service wants to see
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ *
+ * This returns POLLIN, possibly or'd with POLLOUT if there are writes
+ * pending. You can set this straight into poll.events.
+ *
+ * See Also:
+ * ctdb_service()
+ */
int ctdb_which_events(struct ctdb_connection *ctdb);
-int ctdb_service(struct ctdb_connection *ctdb, int revents);
+/**
+ * ctdb_service - service any I/O and callbacks from ctdbd communication
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @revents: which events are available.
+ *
+ * This is the core of the library: it read and writes to the ctdbd
+ * socket. It may call callbacks registered with the various _send
+ * functions.
+ *
+ * revents is a bitset: POLLIN and/or POLLOUT may be set to indicate
+ * it is worth attempting to read/write the (nonblocking)
+ * filedescriptor respectively.
+ *
+ * Note that the synchronous functions call this internally.
+ * Returns false on catastrophic failure.
+ */
+bool ctdb_service(struct ctdb_connection *ctdb, int revents);
+/**
+ * struct ctdb_request - handle for an outstanding request
+ *
+ * This opaque structure returned from various *_send functions gives
+ * you a handle by which you can cancel a request. You can't do
+ * anything else with it until the request is completed and it is
+ * handed to your callback function.
+ */
struct ctdb_request;
-void ctdb_request_free(struct ctdb_request *req);
+/**
+ * ctdb_request_free - free a completed request
+ *
+ * This frees a request: you should only call it once it has been
+ * handed to your callback. For incomplete requests, see ctdb_cancel().
+ */
+void ctdb_request_free(struct ctdb_connection *ctdb, struct ctdb_request *req);
-/*
- * Callback for completed requests: it would normally unpack the request
- * using ctdb_*_recv().
- * You must free the request using ctdb_request_free().
+/**
+ * ctdb_callback_t - callback for completed requests.
*
- * Note that due to macro magic, your callback doesn't have to take void *,
- * it can take a type which matches the actual private parameter.
+ * This would normally unpack the request using ctdb_*_recv(). You
+ * must free the request using ctdb_request_free().
+ *
+ * Note that due to macro magic, actual your callback can be typesafe:
+ * instead of taking a void *, it can take a type which matches the
+ * actual private parameter.
*/
typedef void (*ctdb_callback_t)(struct ctdb_connection *ctdb,
struct ctdb_request *req, void *private);
-/*
- * Special node addresses :
- */
-/* used on the domain socket, send a pdu to the local daemon */
-#define CTDB_CURRENT_NODE 0xF0000001
-/* send a broadcast to all nodes in the cluster, active or not */
-#define CTDB_BROADCAST_ALL 0xF0000002
-/* send a broadcast to all nodes in the current vnn map */
-#define CTDB_BROADCAST_VNNMAP 0xF0000003
-/* send a broadcast to all connected nodes */
-#define CTDB_BROADCAST_CONNECTED 0xF0000004
-
-
-/*
- * functions to attach to a database
- * if the database does not exist it will be created.
+/**
+ * struct ctdb_db - connection to a particular open TDB
+ *
+ * This represents a particular open database: you receive it from
+ * ctdb_attachdb or ctdb_attachdb_recv to manipulate a database.
*
* You have to free the handle with ctdb_detach_db() when finished with it.
*/
struct ctdb_db;
+/**
+ * ctdb_attachdb_send - open a clustered TDB
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @name: the filename of the database (no /).
+ * @persistent: whether the database is persistent across ctdbd's life
+ * @tdb_flags: the flags to pass to tdb_open.
+ * @callback: the callback when we're attached or failed (typesafe)
+ * @cbdata: the argument to callback()
+ *
+ * This function connects to a TDB controlled by ctdbd. It can create
+ * a new TDB if it does not exist, depending on tdb_flags. Returns
+ * the pending request, or NULL on error.
+ */
struct ctdb_request *
ctdb_attachdb_send(struct ctdb_connection *ctdb,
const char *name, int persistent, uint32_t tdb_flags,
- ctdb_callback_t callback, void *private_data);
+ ctdb_callback_t callback, void *cbdata);
-struct ctdb_db *ctdb_attachdb_recv(struct ctdb_request *req);
+/**
+ * ctdb_attachdb_recv - read an ctdb_attach reply from ctdbd
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @req: the completed request.
+ *
+ * This returns NULL if something went wrong, or otherwise the open database.
+ */
+struct ctdb_db *ctdb_attachdb_recv(struct ctdb_connection *ctdb,
+ struct ctdb_request *req);
-struct ctdb_db *ctdb_attachdb(struct ctdb_connection *ctdb,
- const char *name, int persistent,
- uint32_t tdb_flags);
+/**
+ * struct ctdb_lock - a record lock on a clustered TDB database
+ *
+ * This locks a subset of the database across the entire cluster; it
+ * is the fundamental sychronization element for ctdb. You cannot have
+ * more than one lock at once.
+ *
+ * You MUST NOT block during holding this lock and MUST release it
+ * quickly by performing ctdb_release_lock(lock).
+ */
struct ctdb_lock;
-/*
- * functions to read a record from the database
- * when the callback is invoked, the client will hold an exclusive lock
- * on the record, the client MUST NOT block during holding this lock and MUST
- * release it quickly by performing ctdb_release_lock(lock).
+/**
+ * ctdb_rrl_callback_t - callback for ctdb_readrecordlock_async
*
- * When the lock is released, data is freed too, so make sure to copy the data
- * before that.
+ * This is not the standard ctdb_callback_t, because there is often no
+ * request required to access a database record (ie. if it is local already).
+ * So the callback is handed the lock directly: it might be NULL if there
+ * was an error obtaining the lock.
*
- * This returns true on success: the callback may have already been called,
- * or it might be awaiting a response from ctdbd.
+ * See Also:
+ * ctdb_readrecordlock_async(), ctdb_readrecordlock()
*/
typedef void (*ctdb_rrl_callback_t)(struct ctdb_db *ctdb_db,
struct ctdb_lock *lock,
TDB_DATA data,
void *private);
-bool
-ctdb_readrecordlock_async(struct ctdb_db *ctdb_db, TDB_DATA key,
- ctdb_rrl_callback_t callback, void *private_data);
-/* Returns null on failure. */
-struct ctdb_lock *ctdb_readrecordlock(struct ctdb_db *ctdb_db, TDB_DATA key,
- TDB_DATA *data);
+/**
+ * ctdb_readrecordlock_async - read and lock a record
+ * @ctdb_db: the database handle from ctdb_attachdb/ctdb_attachdb_recv.
+ * @key: the key of the record to lock.
+ * @callback: the callback once the record is locked (typesafe).
+ * @cbdata: the argument to callback()
+ *
+ * This returns true on success. Commonly, we can obtain the record
+ * immediately and so the callback will be invoked. Otherwise a request
+ * will be queued to ctdbd for the record.
+ *
+ * If failure is immediate, false is returned. Otherwise, the callback
+ * may receive a NULL lock arg to indicate asynchronous failure.
+ */
+bool ctdb_readrecordlock_async(struct ctdb_db *ctdb_db, TDB_DATA key,
+ ctdb_rrl_callback_t callback, void *cbdata);
-/*
- * Function to write data to a record
- * This function may ONLY be called while holding a lock to the record
- * created by ctdb_readrecordlock*, and before calling
- * ctdb_release_lock() to release the lock.
+/**
+ * ctdb_writerecord - write a locked record in a TDB
+ * @lock: the lock from ctdb_readrecordlock/ctdb_readrecordlock_recv
+ * @data: the new data to place in the record.
*/
int ctdb_writerecord(struct ctdb_lock *lock, TDB_DATA data);
-
+/**
+ * ctdb_release_lock - release a record lock on a TDB
+ * @lock: the lock from ctdb_readrecordlock/ctdb_readrecordlock_async
+ */
void ctdb_release_lock(struct ctdb_lock *lock);
-/*
- * messaging functions
- * these functions provide a messaging layer for applications to communicate
- * with eachother across
+/**
+ * ctdb_message_fn_t - messaging callback for ctdb messages
+ *
+ * ctdbd provides a simple messaging API; you can register for a particular
+ * 64-bit id on which you want to send messages, and send to other ids.
+ *
+ * See Also:
+ * ctdb_set_message_handler_send()
+ */
+typedef void (*ctdb_message_fn_t)(struct ctdb_connection *,
+ uint64_t srvid, TDB_DATA data, void *);
+
+/**
+ * ctdb_set_message_handler_send - register for messages to a srvid
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @srvid: the 64 bit identifier for our messages.
+ * @handler: the callback when we receive such a message (typesafe)
+ * @callback: the callback when ctdb replies to our message (typesafe)
+ * @cbdata: the argument to callback() and handler()
+ *
+ * Note: our callback will always be called before handler.
+ *
+ * See Also:
+ * ctdb_set_message_handler_recv(), ctdb_remove_message_handler_send()
*/
-typedef void (*ctdb_message_fn_t)(struct ctdb_connection *, uint64_t srvid, TDB_DATA data, void *);
-
struct ctdb_request *
ctdb_set_message_handler_send(struct ctdb_connection *ctdb, uint64_t srvid,
ctdb_message_fn_t handler,
ctdb_callback_t callback,
- void *private_data);
-
-int ctdb_set_message_handler_recv(struct ctdb_connection *ctdb,
- struct ctdb_request *handle);
-
-int ctdb_set_message_handler(struct ctdb_connection *ctdb, uint64_t srvid,
- ctdb_message_fn_t handler, void *private_data);
+ void *cbdata);
-
-
-/*
- * unregister a message handler and stop listening on teh specified port
+/**
+ * ctdb_set_message_handler_recv - read a set_message_handler result
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @req: the completed request
+ *
+ * If this returns true, the registered handler may be called from the next
+ * ctdb_service(). If this returns false, the registration failed.
+ */
+bool ctdb_set_message_handler_recv(struct ctdb_connection *ctdb,
+ struct ctdb_request *handle);
+
+/**
+ * ctdb_remove_message_handler_send - unregister for messages to a srvid
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @srvid: the 64 bit identifier for our messages.
+ * @callback: the callback when ctdb replies to our message (typesafe)
+ * @cbdata: the argument to callback()
+ *
+ * This undoes a successful ctdb_set_message_handler or
+ * ctdb_set_message_handler_recv.
*/
struct ctdb_request *
ctdb_remove_message_handler_send(struct ctdb_connection *ctdb, uint64_t srvid,
- ctdb_callback_t callback,
- void *private_data);
-
-int ctdb_remove_message_handler_recv(struct ctdb_request *handle);
-
-int ctdb_remove_message_handler(struct ctdb_connection *ctdb, uint64_t srvid);
+ ctdb_callback_t callback, void *cbdata);
-
-
-/*
- * send a message to a specific node/port
- * this function is non-blocking
+/**
+ * ctdb_remove_message_handler_recv - read a remove_message_handler result
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @req: the completed request
+ *
+ * After this returns true, the registered handler will no longer be called.
+ * If this returns false, the de-registration failed.
*/
-int ctdb_send_message(struct ctdb_connection *ctdb, uint32_t pnn, uint64_t srvid, TDB_DATA data);
+bool ctdb_remove_message_handler_recv(struct ctdb_request *handle);
-
-/*
- * functions to read the pnn number of the local node
+/**
+ * ctdb_send_message - send a message via ctdbd
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @pnn: the physical node number to send to
+ * @srvid: the 64 bit identifier for this message type.
+ * @data: the data to send
+ *
+ * This allows arbitrary messages to be sent across the cluster to those
+ * listening (via ctdb_set_message_handler et al).
+ *
+ * This queues a message to be sent: you will need to call
+ * ctdb_service() to actually send the message. There is no callback
+ * because there is no acknowledgement.
+ *
+ * See Also:
+ * ctdb_getpnn_send(), ctdb_getpnn()
+ */
+bool ctdb_send_message(struct ctdb_connection *ctdb, uint32_t pnn, uint64_t srvid, TDB_DATA data);
+
+/**
+ * ctdb_getpnn_send - read the pnn number of a node.
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @destnode: the destination node (see below)
+ * @callback: the callback when ctdb replies to our message (typesafe)
+ * @cbdata: the argument to callback()
+ *
+ * There are several special values for destnode, detailed in
+ * ctdb_protocol.h, particularly CTDB_CURRENT_NODE which means the
+ * local ctdbd.
*/
struct ctdb_request *
ctdb_getpnn_send(struct ctdb_connection *ctdb,
uint32_t destnode,
ctdb_callback_t callback,
- void *private_data);
-int ctdb_getpnn_recv(struct ctdb_request *req, uint32_t *pnn);
-
-int ctdb_getpnn(struct ctdb_connection *ctdb,
- uint32_t destnode,
- uint32_t *pnn);
-
-
+ void *cbdata);
+/**
+ * ctdb_getpnn_recv - read an ctdb_getpnn reply from ctdbd
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @req: the completed request.
+ * @pnn: a pointer to the pnn to fill in
+ *
+ * This returns false if something went wrong, or otherwise fills in pnn.
+ */
+bool ctdb_getpnn_recv(struct ctdb_connection *ctdb,
+ struct ctdb_request *req, uint32_t *pnn);
-/*
- * functions to read the recovery master of a node
+/**
+ * ctdb_getrecmaster_send - read the recovery master of a node
+ * @ctdb: the ctdb_connection from ctdb_connect.
+ * @destnode: the destination node (see below)
+ * @callback: the callback when ctdb replies to our message (typesafe)
+ * @cbdata: the argument to callback()
+ *
+ * There are several special values for destnode, detailed in
+ * ctdb_protocol.h, particularly CTDB_CURRENT_NODE which means the
+ * local ctdbd.
*/
struct ctdb_request *
ctdb_getrecmaster_send(struct ctdb_connection *ctdb,
uint32_t destnode,
- ctdb_callback_t callback,
- void *private_data);
-int ctdb_getrecmaster_recv(struct ctdb_request *handle,
- uint32_t *recmaster);
-int ctdb_getrecmaster(struct ctdb_connection *ctdb,
- uint32_t destnode,
- uint32_t *recmaster);
+ ctdb_callback_t callback, void *cbdata);
+/**
+ * ctdb_getrecmaster_recv - read an ctdb_getrecmaster reply from ctdbd
+ * @ctdb: the ctdb_connection from ctdb_connect.
--
CTDB repository
More information about the samba-cvs
mailing list