From bdbc97c4527f20c531f4c11d97cbde8bb62f1c03 Mon Sep 17 00:00:00 2001 From: "A.J. Beamon" Date: Tue, 10 Dec 2019 12:38:37 -0800 Subject: [PATCH 1/2] Add docuentation about opening connections to multiple clusters --- bindings/go/src/fdb/cluster.go | 4 +-- bindings/go/src/fdb/fdb.go | 19 +++++++++--- .../src/main/com/apple/foundationdb/FDB.java | 29 ++++++++++++++----- documentation/sphinx/source/api-c.rst | 2 ++ .../sphinx/source/api-common.rst.inc | 7 +++-- documentation/sphinx/source/api-python.rst | 4 ++- documentation/sphinx/source/api-ruby.rst | 4 ++- 7 files changed, 52 insertions(+), 17 deletions(-) diff --git a/bindings/go/src/fdb/cluster.go b/bindings/go/src/fdb/cluster.go index 275a036338..3ec92c2c5e 100644 --- a/bindings/go/src/fdb/cluster.go +++ b/bindings/go/src/fdb/cluster.go @@ -26,7 +26,7 @@ package fdb // #include import "C" -// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly +// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly. // Cluster is a handle to a FoundationDB cluster. Cluster is a lightweight // object that may be efficiently copied, and is safe for concurrent use by // multiple goroutines. @@ -34,7 +34,7 @@ type Cluster struct { clusterFileName string } -// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly +// Deprecated: Use OpenDatabase or OpenDefault to obtain a database handle directly. // OpenDatabase returns a database handle from the FoundationDB cluster. // // The database name must be []byte("DB"). diff --git a/bindings/go/src/fdb/fdb.go b/bindings/go/src/fdb/fdb.go index 3910a980c3..32c8a2e094 100644 --- a/bindings/go/src/fdb/fdb.go +++ b/bindings/go/src/fdb/fdb.go @@ -236,8 +236,12 @@ func StartNetwork() error { const DefaultClusterFile string = "" // OpenDefault returns a database handle to the FoundationDB cluster identified -// by the DefaultClusterFile on the current machine. The FoundationDB client -// networking engine will be initialized first, if necessary. +// by the DefaultClusterFile on the current machine. +// +// A single client can use this function multiple times to connect to different +// clusters simultaneously, with each invocation requiring its own cluster file. +// To connect to multiple clusters running at different, incompatible versions, +// the multi-version client API must be used. func OpenDefault() (Database, error) { return OpenDatabase(DefaultClusterFile) } @@ -254,6 +258,11 @@ func MustOpenDefault() Database { // Open returns a database handle to the FoundationDB cluster identified // by the provided cluster file and database name. +// +// A single client can use this function multiple times to connect to different +// clusters simultaneously, with each invocation requiring its own cluster file. +// To connect to multiple clusters running at different, incompatible versions, +// the multi-version client API must be used. func OpenDatabase(clusterFile string) (Database, error) { networkMutex.Lock() defer networkMutex.Unlock() @@ -283,6 +292,8 @@ func OpenDatabase(clusterFile string) (Database, error) { return db, nil } +// MustOpenDatabase is like OpenDatabase but panics if the default database cannot +// be opened. func MustOpenDatabase(clusterFile string) Database { db, err := OpenDatabase(clusterFile) if err != nil { @@ -291,7 +302,7 @@ func MustOpenDatabase(clusterFile string) Database { return db } -// Deprecated: Use OpenDatabase instead +// Deprecated: Use OpenDatabase instead. // The database name must be []byte("DB"). func Open(clusterFile string, dbName []byte) (Database, error) { if bytes.Compare(dbName, []byte("DB")) != 0 { @@ -300,7 +311,7 @@ func Open(clusterFile string, dbName []byte) (Database, error) { return OpenDatabase(clusterFile) } -// Deprecated: Use MustOpenDatabase instead +// Deprecated: Use MustOpenDatabase instead. // MustOpen is like Open but panics if the database cannot be opened. func MustOpen(clusterFile string, dbName []byte) Database { db, err := Open(clusterFile, dbName) diff --git a/bindings/java/src/main/com/apple/foundationdb/FDB.java b/bindings/java/src/main/com/apple/foundationdb/FDB.java index 621417256d..f105f91983 100644 --- a/bindings/java/src/main/com/apple/foundationdb/FDB.java +++ b/bindings/java/src/main/com/apple/foundationdb/FDB.java @@ -292,9 +292,14 @@ public class FDB { } /** - * Initializes networking, connects with the - * default fdb.cluster file, - * and opens the database. + * Initializes networking if required and connects to the cluster specified by the + * default fdb.cluster file.
+ *
+ * A single client can use this function multiple times to connect to different + * clusters simultaneously, with each invocation requiring its own cluster file. + * To connect to multiple clusters running at different, incompatible versions, + * the multi-version client API + * must be used. * * @return a {@code CompletableFuture} that will be set to a FoundationDB {@link Database} */ @@ -303,8 +308,13 @@ public class FDB { } /** - * Initializes networking, connects to the cluster specified by {@code clusterFilePath} - * and opens the database. + * Initializes networking if required and connects to the cluster specified by {@code clusterFilePath}.
+ *
+ * A single client can use this function multiple times to connect to different + * clusters simultaneously, with each invocation requiring its own cluster file. + * To connect to multiple clusters running at different, incompatible versions, + * the multi-version client API + * must be used. * * @param clusterFilePath the * cluster file @@ -319,8 +329,13 @@ public class FDB { } /** - * Initializes networking, connects to the cluster specified by {@code clusterFilePath} - * and opens the database. + * Initializes networking if required and connects to the cluster specified by {@code clusterFilePath}.
+ *
+ * A single client can use this function multiple times to connect to different + * clusters simultaneously, with each invocation requiring its own cluster file. + * To connect to multiple clusters running at different, incompatible versions, + * the multi-version client API + * must be used. * * @param clusterFilePath the * cluster file diff --git a/documentation/sphinx/source/api-c.rst b/documentation/sphinx/source/api-c.rst index 33e9169034..ad019d42e6 100644 --- a/documentation/sphinx/source/api-c.rst +++ b/documentation/sphinx/source/api-c.rst @@ -393,6 +393,8 @@ An |database-blurb1| Modifications to a database are performed via transactions. Creates a new database connected the specified cluster. The caller assumes ownership of the :type:`FDBDatabase` object and must destroy it with :func:`fdb_database_destroy()`. + |fdb-open-blurb2| + ``cluster_file_path`` A NULL-terminated string giving a local path of a :ref:`cluster file ` (often called 'fdb.cluster') which contains connection information for the FoundationDB cluster. If cluster_file_path is NULL or an empty string, then a :ref:`default cluster file ` will be used. diff --git a/documentation/sphinx/source/api-common.rst.inc b/documentation/sphinx/source/api-common.rst.inc index 23b2b22045..85c5c525da 100644 --- a/documentation/sphinx/source/api-common.rst.inc +++ b/documentation/sphinx/source/api-common.rst.inc @@ -448,8 +448,11 @@ Cancels |future-type-string| and its associated asynchronous operation. If called before the future is ready, attempts to access its value will |error-raise-type| an :ref:`operation_cancelled ` |error-type|. Cancelling a future which is already ready has no effect. Note that even if a future is not ready, its associated asynchronous operation may have succesfully completed and be unable to be cancelled. -.. |fdb-open-blurb| replace:: - Initializes the FoundationDB API and connects to the cluster specified by the :ref:`cluster file `. This function is often called without any parameters, using only the defaults. If no cluster file is passed, FoundationDB automatically :ref:`determines a cluster file ` with which to connect to a cluster. +.. |fdb-open-blurb1| replace:: + Connects to the cluster specified by the :ref:`cluster file `. This function is often called without any parameters, using only the defaults. If no cluster file is passed, FoundationDB automatically :ref:`determines a cluster file ` with which to connect to a cluster. + +.. |fdb-open-blurb2| replace:: + A single client can use this function multiple times to connect to different clusters simultaneously, with each invocation requiring its own cluster file. To connect to multiple clusters running at different, incompatible versions, the :ref:`multi-version client API ` must be used. .. |fdb-transactional-unknown-result-note| replace:: In some failure scenarios, it is possible that your transaction will be executed twice. See :ref:`developer-guide-unknown-results` for more information. diff --git a/documentation/sphinx/source/api-python.rst b/documentation/sphinx/source/api-python.rst index 7ba7b4421e..2eff885d05 100644 --- a/documentation/sphinx/source/api-python.rst +++ b/documentation/sphinx/source/api-python.rst @@ -111,7 +111,9 @@ After importing the ``fdb`` module and selecting an API version, you probably wa .. function:: open( cluster_file=None, event_model=None ) - |fdb-open-blurb| + |fdb-open-blurb1| + + |fdb-open-blurb2| .. param event_model:: Can be used to select alternate :ref:`api-python-event-models` diff --git a/documentation/sphinx/source/api-ruby.rst b/documentation/sphinx/source/api-ruby.rst index f033ae2e2e..ae28bd224b 100644 --- a/documentation/sphinx/source/api-ruby.rst +++ b/documentation/sphinx/source/api-ruby.rst @@ -100,7 +100,9 @@ After requiring the ``FDB`` gem and selecting an API version, you probably want .. function:: open( cluster_file=nil ) -> Database - |fdb-open-blurb| + |fdb-open-blurb1| + + |fdb-open-blurb2| .. global:: FDB.options From d09e3e1d96172b359f860a7de4e4cf73f1c039a1 Mon Sep 17 00:00:00 2001 From: "A.J. Beamon" Date: Tue, 10 Dec 2019 13:42:30 -0800 Subject: [PATCH 2/2] Apply go fmt. --- bindings/go/src/fdb/fdb.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bindings/go/src/fdb/fdb.go b/bindings/go/src/fdb/fdb.go index 32c8a2e094..7d0f17fbe1 100644 --- a/bindings/go/src/fdb/fdb.go +++ b/bindings/go/src/fdb/fdb.go @@ -236,7 +236,7 @@ func StartNetwork() error { const DefaultClusterFile string = "" // OpenDefault returns a database handle to the FoundationDB cluster identified -// by the DefaultClusterFile on the current machine. +// by the DefaultClusterFile on the current machine. // // A single client can use this function multiple times to connect to different // clusters simultaneously, with each invocation requiring its own cluster file.