fdb

package
v0.0.0-...-4ef6bca Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 10, 2024 License: Apache-2.0 Imports: 8 Imported by: 141

Documentation

Overview

Package fdb provides an interface to FoundationDB databases (version 2.0 or higher).

To build and run programs using this package, you must have an installed copy of the FoundationDB client libraries (version 2.0.0 or later), available for Linux, Windows and OS X at https://github.com/apple/foundationdb/releases

This documentation specifically applies to the FoundationDB Go binding. For more extensive guidance to programming with FoundationDB, as well as API documentation for the other FoundationDB interfaces, please see https://apple.github.io/foundationdb/index.html.

Basic Usage

A basic interaction with the FoundationDB API is demonstrated below: 

package main

import (
    "github.com/apple/foundationdb/bindings/go/src/fdb"
    "log"
    "fmt"
)

func main() {
    // Different API versions may expose different runtime behaviors.
    fdb.MustAPIVersion(740)

    // Open the default database from the system cluster
    db := fdb.MustOpenDefault()

    // Database reads and writes happen inside transactions
    ret, e := db.Transact(func(tr fdb.Transaction) (interface{}, error) {
        tr.Set(fdb.Key("hello"), []byte("world"))
        return tr.Get(fdb.Key("foo")).MustGet(), nil
        // db.Transact automatically commits (and if necessary,
        // retries) the transaction
    })
    if e != nil {
        log.Fatalf("Unable to perform FDB transaction (%v)", e)
    }

    fmt.Printf("hello is now world, foo was: %s\n", string(ret.([]byte)))
}

Futures

Many functions in this package are asynchronous and return Future objects. A Future represents a value (or error) to be available at some later time. Functions documented as blocking on a Future will block the calling goroutine until the Future is ready (although if the Future is already ready, the call will not block at all). While a goroutine is blocked on a Future, other goroutines are free to execute and interact with the FoundationDB API.

It is possible (and often recommended) to call several asynchronous operations and have multiple Future objects outstanding inside a single goroutine. All operations will execute in parallel, and the calling goroutine will not block until a blocking method on any one of the Futures is called.

On Panics

Idiomatic Go code strongly frowns at panics that escape library/package boundaries, in favor of explicitly returned errors. Idiomatic FoundationDB client programs, however, are built around the idea of retryable programmer-provided transactional functions. Retryable transactions can be implemented using only error values: 

ret, e := db.Transact(func (tr Transaction) (interface{}, error) {
    // FoundationDB futures represent a value that will become available
    futureValueOne := tr.Get(fdb.Key("foo"))
    futureValueTwo := tr.Get(fdb.Key("bar"))

    // Both reads are being carried out in parallel

    // Get the first value (or any error)
    valueOne, e := futureValueOne.Get()
    if e != nil {
        return nil, e
    }

    // Get the second value (or any error)
    valueTwo, e := futureValueTwo.Get()
    if e != nil {
        return nil, e
    }

    // Return the two values
    return []string{valueOne, valueTwo}, nil
})

If either read encounters an error, it will be returned to Transact, which will determine if the error is retryable or not (using (Transaction).OnError). If the error is an FDB Error and retryable (such as a conflict with with another transaction), then the programmer-provided function will be run again. If the error is fatal (or not an FDB Error), then the error will be returned to the caller of Transact.

In practice, checking for an error from every asynchronous future type in the FoundationDB API quickly becomes frustrating. As a convenience, every Future type also has a MustGet method, which returns the same type and value as Get, but exposes FoundationDB Errors via a panic rather than an explicitly returned error. The above example may be rewritten as: 

ret, e := db.Transact(func (tr Transaction) (interface{}, error) {
    // FoundationDB futures represent a value that will become available
    futureValueOne := tr.Get(fdb.Key("foo"))
    futureValueTwo := tr.Get(fdb.Key("bar"))

    // Both reads are being carried out in parallel

    // Get the first value
    valueOne := futureValueOne.MustGet()
    // Get the second value
    valueTwo := futureValueTwo.MustGet()

    // Return the two values
    return []string{valueOne, valueTwo}, nil
})

MustGet returns nil (which is different from empty slice []byte{}), when the key doesn't exist, and hence non-existence can be checked as follows: 

val := tr.Get(fdb.Key("foobar")).MustGet()
if val == nil {
  fmt.Println("foobar does not exist.")
} else {
  fmt.Println("foobar exists.")
}

Any panic that occurs during execution of the caller-provided function will be recovered by the (Database).Transact method. If the error is an FDB Error, it will either result in a retry of the function or be returned by Transact. If the error is any other type (panics from code other than MustGet), Transact will re-panic the original value.

Note that (Transaction).Transact also recovers panics, but does not itself retry. If the recovered value is an FDB Error, it will be returned to the caller of (Transaction).Transact; all other values will be re-panicked.

Transactions and Goroutines

When using a Transactor in the fdb package, particular care must be taken if goroutines are created inside of the function passed to the Transact method. Any panic from the goroutine will not be recovered by Transact, and (unless otherwise recovered) will result in the termination of that goroutine.

Furthermore, any errors returned or panicked by fdb methods called in the goroutine must be safely returned to the function passed to Transact, and either returned or panicked, to allow Transact to appropriately retry or terminate the transactional function.

Lastly, a transactional function may be retried indefinitely. It is advisable to make sure any goroutines created during the transactional function have completed before returning from the transactional function, or a potentially unbounded number of goroutines may be created.

Given these complexities, it is generally best practice to use a single goroutine for each logical thread of interaction with FoundationDB, and allow each goroutine to block when necessary to wait for Futures to become ready.

Streaming Modes

When using GetRange methods in the FoundationDB API, clients can request large ranges of the database to iterate over. Making such a request doesn't necessarily mean that the client will consume all of the data in the range -- sometimes the client doesn't know how far it intends to iterate in advance. FoundationDB tries to balance latency and bandwidth by requesting data for iteration in batches.

The Mode field of the RangeOptions struct allows a client to customize this performance tradeoff by providing extra information about how the iterator will be used.

The default value of Mode is StreamingModeIterator, which tries to provide a reasonable default balance. Other streaming modes that prioritize throughput or latency are available -- see the documented StreamingMode values for specific options.

Atomic Operations

The FDB package provides a number of atomic operations on the Database and Transaction objects. An atomic operation is a single database command that carries out several logical steps: reading the value of a key, performing a transformation on that value, and writing the result. Different atomic operations perform different transformations. Like other database operations, an atomic operation is used within a transaction.

For more information on atomic operations in FoundationDB, please see https://apple.github.io/foundationdb/developer-guide.html#atomic-operations. The operands to atomic operations in this API must be provided as appropriately encoded byte slices. To convert a Go type to a byte slice, see the binary package.

The current atomic operations in this API are Add, BitAnd, BitOr, BitXor, CompareAndClear, Max, Min, SetVersionstampedKey, SetVersionstampedValue (all methods on Transaction).

Index

Examples

Constants

View Source 
const DefaultClusterFile string = ""

DefaultClusterFile should be passed to fdb.Open to allow the FoundationDB C library to select the platform-appropriate default cluster file on the current machine.

Variables

View Source 
var (
	// ErrNetworkAlreadyStopped for multiple calls to StopNetwork().
	ErrNetworkAlreadyStopped = errors.New("network has already been stopped")

	// ErrNetworkIsStopped is returned when attempting to execute a function which needs to interact
	// with the network thread while the network thread is no more running.
	ErrNetworkIsStopped = errors.New("network is stopped")

	// ErrNetworkAlreadyStopped for a too early call to StopNetwork().
	ErrNetworkNotStarted = errors.New("network has not been started")
)

Functions

func APIVersion 

func APIVersion(version int) error

APIVersion determines the runtime behavior the fdb package. If the requested version is not supported by both the fdb package and the FoundationDB C library, an error will be returned. APIVersion must be called prior to any other functions in the fdb package. This function is safe to be called from multiple goroutines.

Currently, this package supports API versions 200 through 740.

Warning: When using the multi-version client API, setting an API version that is not supported by a particular client library will prevent that client from being used to connect to the cluster. In particular, you should not advance the API version of your application after upgrading your client until the cluster has also been upgraded.

func GetAPIVersion 

func GetAPIVersion() (int, error)

Returns the API version that has been selected through APIVersion or MustAPIVersion. If the version has already been selected, then the first value returned is the API version and the error is nil. If the API version has not yet been set, then the error will be non-nil.

func IsAPIVersionSelected 

func IsAPIVersionSelected() bool

Determines if an API version has already been selected, i.e., if APIVersion or MustAPIVersion have already been called.

func MustAPIVersion 

func MustAPIVersion(version int)

MustAPIVersion is like APIVersion but panics if the API version is not supported.

func MustGetAPIVersion 

func MustGetAPIVersion() int

MustGetAPIVersion is like GetAPIVersion but panics if the API version has not yet been set.

func Printable 

func Printable(d []byte) string

Printable returns a human readable version of a byte array. The bytes that correspond with ASCII printable characters [32-127) are passed through. Other bytes are replaced with \x followed by a two character zero-padded hex code for byte.

Example 
package main

import (
	"fmt"

	"github.com/apple/foundationdb/bindings/go/src/fdb"
)

func main() {
	fmt.Println(fdb.Printable([]byte{0, 1, 2, 'a', 'b', 'c', '1', '2', '3', '!', '?', 255}))
}

Output:

\x00\x01\x02abc123!?\xff

func StartNetwork deprecated 

func StartNetwork() error

Deprecated: the network is started automatically when a database is opened. StartNetwork does nothing, but it will ensure that the API version is set and return an error otherwise.

func StopNetwork 

func StopNetwork() error

StopNetwork signals the internal network event loop to terminate and waits for its termination. This function is safe to be called from multiple goroutines. This function returns an error if network has not yet started or if network has already been stopped. See also: https://github.com/apple/foundationdb/issues/3015

func Strinc 

func Strinc(prefix []byte) ([]byte, error)

Strinc returns the first key that would sort outside the range prefixed by prefix, or an error if prefix is empty or contains only 0xFF bytes.

Types

type Cluster deprecated 

type Cluster struct {
	// contains filtered or unexported fields
}

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.

func CreateCluster deprecated 

func CreateCluster(clusterFile string) (Cluster, error)

Deprecated: Use OpenDatabase instead. CreateCluster returns a cluster handle to the FoundationDB cluster identified by the provided cluster file. This function is safe to be called from multiple goroutines.

func (Cluster) OpenDatabase deprecated 

func (c Cluster) OpenDatabase(dbName []byte) (Database, error)

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").

type Database 

type Database struct {
	// contains filtered or unexported fields
}

Database is a handle to a FoundationDB database. Database is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

Although Database provides convenience methods for reading and writing data, modifications to a database are usually made via transactions, which are usually created and committed automatically by the (Database).Transact method.

func MustOpen deprecated 

func MustOpen(clusterFile string, dbName []byte) Database

Deprecated: Use MustOpenDatabase instead. MustOpen is like Open but panics if the database cannot be opened.

func MustOpenDatabase 

func MustOpenDatabase(clusterFile string) Database

MustOpenDatabase is like OpenDatabase but panics if the default database cannot be opened.

func MustOpenDefault 

func MustOpenDefault() Database

MustOpenDefault is like OpenDefault but panics if the default database cannot be opened.

func Open deprecated 

func Open(clusterFile string, dbName []byte) (Database, error)

Deprecated: Use OpenDatabase instead. The database name must be []byte("DB").

func OpenDatabase 

func OpenDatabase(clusterFile string) (Database, error)

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. Caller must call Close() to release resources.

func OpenDefault 

func OpenDefault() (Database, error)

OpenDefault returns a database handle to the FoundationDB cluster identified 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.

Example 
package main

import (
	"fmt"

	"github.com/apple/foundationdb/bindings/go/src/fdb"
)

const API_VERSION int = 740

func main() {
	var e error

	e = fdb.APIVersion(API_VERSION)
	if e != nil {
		fmt.Printf("Unable to set API version: %v\n", e)
		return
	}

	// OpenDefault opens the database described by the platform-specific default
	// cluster file
	db, e := fdb.OpenDefault()
	if e != nil {
		fmt.Printf("Unable to open default database: %v\n", e)
		return
	}

	// Close the database after usage
	defer db.Close()

	// Do work here

}

Output:

func OpenWithConnectionString 

func OpenWithConnectionString(connectionString string) (Database, error)

OpenWithConnectionString returns a database handle to the FoundationDB cluster identified by the provided connection string. This method can be useful for scenarios where you want to connect to the database only for a short time e.g. to test different connection strings. Caller must call Close() to release resources.

Example 
package main

import (
	"fmt"
	"os"

	"github.com/apple/foundationdb/bindings/go/src/fdb"
)

const API_VERSION int = 740

func main() {
	fdb.MustAPIVersion(API_VERSION)

	clusterFileContent, err := os.ReadFile(os.Getenv("FDB_CLUSTER_FILE"))
	if err != nil {
		fmt.Errorf("Unable to read cluster file: %v\n", err)
		return
	}

	// OpenWithConnectionString opens the database described by the connection string
	db, err := fdb.OpenWithConnectionString(string(clusterFileContent))
	if err != nil {
		fmt.Errorf("Unable to open database: %v\n", err)
		return
	}

	// Close the database after usage
	defer db.Close()

	// Do work here

}

Output:

func (Database) Close 

func (d Database) Close()

Close will close the Database and clean up all resources. It must be called exactly once for each created database. You have to ensure that you're not reusing this database after it has been closed.

func (Database) CreateTransaction 

func (d Database) CreateTransaction() (Transaction, error)

CreateTransaction returns a new FoundationDB transaction. It is generally preferable to use the (Database).Transact method, which handles automatically creating and committing a transaction with appropriate retry behavior.

func (Database) LocalityGetBoundaryKeys 

func (d Database) LocalityGetBoundaryKeys(er ExactRange, limit int, readVersion int64) ([]Key, error)

LocalityGetBoundaryKeys returns a slice of keys that fall within the provided range. Each key is located at the start of a contiguous range stored on a single server.

If limit is non-zero, only the first limit keys will be returned. In large databases, the number of boundary keys may be large. In these cases, a non-zero limit should be used, along with multiple calls to LocalityGetBoundaryKeys.

If readVersion is non-zero, the boundary keys as of readVersion will be returned.

func (Database) Options 

func (d Database) Options() DatabaseOptions

Options returns a DatabaseOptions instance suitable for setting options specific to this database.

func (Database) ReadTransact 

func (d Database) ReadTransact(f func(ReadTransaction) (interface{}, error)) (interface{}, error)

ReadTransact runs a caller-provided function inside a retry loop, providing it with a newly created Transaction (as a ReadTransaction). Any error during execution of the function (by panic or return) will cause the function to be retried or, if fatal, return the error to the caller.

When working with Future objects in a read-only transactional function, you may either explicitly check and return error values using Get, or call MustGet. ReadTransact will recover a panicked Error and either retry the transaction or return the error.

The transaction is retried if the error is or wraps a retryable Error. The error is unwrapped. Read transactions are never committed and destroyed before returning to caller.

Do not return Future objects from the function provided to ReadTransact. The Transaction created by ReadTransact may be finalized at any point after ReadTransact returns, resulting in the cancellation of any outstanding reads. Additionally, any errors returned or panicked by the Future will no longer be able to trigger a retry of the caller-provided function.

See the ReadTransactor interface for an example of using ReadTransact with Transaction, Snapshot and Database objects.

func (Database) RebootWorker 

func (d Database) RebootWorker(address string, checkFile bool, suspendDuration int) error

RebootWorker is a wrapper around fdb_database_reboot_worker and allows to reboot processes from the go bindings. If a suspendDuration > 0 is provided the rebooted process will be suspended for suspendDuration seconds. If checkFile is set to true the process will check if the data directory is writeable by creating a validation file. The address must be a process address is the form of IP:Port pair.

func (Database) Transact 

func (d Database) Transact(f func(Transaction) (interface{}, error)) (interface{}, error)

Transact runs a caller-provided function inside a retry loop, providing it with a newly created Transaction. After the function returns, the Transaction will be committed automatically. Any error during execution of the function (by panic or return) or the commit will cause the function and commit to be retried or, if fatal, return the error to the caller.

When working with Future objects in a transactional function, you may either explicitly check and return error values using Get, or call MustGet. Transact will recover a panicked Error and either retry the transaction or return the error.

The transaction is retried if the error is or wraps a retryable Error. The error is unwrapped.

Do not return Future objects from the function provided to Transact. The Transaction created by Transact may be finalized at any point after Transact returns, resulting in the cancellation of any outstanding reads. Additionally, any errors returned or panicked by the Future will no longer be able to trigger a retry of the caller-provided function.

See the Transactor interface for an example of using Transact with Transaction and Database objects.

type DatabaseOptions 

type DatabaseOptions struct {
	// contains filtered or unexported fields
}

DatabaseOptions is a handle with which to set options that affect a Database object. A DatabaseOptions instance should be obtained with the (Database).Options method.

func (DatabaseOptions) SetDatacenterId 

func (o DatabaseOptions) SetDatacenterId(param string) error

Specify the datacenter ID that was passed to fdbserver processes running in the same datacenter as this client, for better location-aware load balancing.

Parameter: A string identifier for the datacenter

func (DatabaseOptions) SetLocationCacheSize 

func (o DatabaseOptions) SetLocationCacheSize(param int64) error

Set the size of the client location cache. Raising this value can boost performance in very large databases where clients access data in a near-random pattern. Defaults to 100000.

Parameter: Max location cache entries

func (DatabaseOptions) SetMachineId 

func (o DatabaseOptions) SetMachineId(param string) error

Specify the machine ID that was passed to fdbserver processes running on the same machine as this client, for better location-aware load balancing.

Parameter: Hexadecimal ID

func (DatabaseOptions) SetMaxWatches 

func (o DatabaseOptions) SetMaxWatches(param int64) error

Set the maximum number of watches allowed to be outstanding on a database connection. Increasing this number could result in increased resource usage. Reducing this number will not cancel any outstanding watches. Defaults to 10000 and cannot be larger than 1000000.

Parameter: Max outstanding watches

func (DatabaseOptions) SetSnapshotRywDisable 

func (o DatabaseOptions) SetSnapshotRywDisable() error

Snapshot read operations will not see the results of writes done in the same transaction. This was the default behavior prior to API version 300.

func (DatabaseOptions) SetSnapshotRywEnable 

func (o DatabaseOptions) SetSnapshotRywEnable() error

Snapshot read operations will see the results of writes done in the same transaction. This is the default behavior.

func (DatabaseOptions) SetTestCausalReadRisky 

func (o DatabaseOptions) SetTestCausalReadRisky(param int64) error

Enables verification of causal read risky by checking whether clients are able to read stale data when they detect a recovery, and logging an error if so.

Parameter: integer between 0 and 100 expressing the probability a client will verify it can't read stale data

func (DatabaseOptions) SetTransactionAutomaticIdempotency 

func (o DatabaseOptions) SetTransactionAutomaticIdempotency() error

Set a random idempotency id for all transactions. See the transaction option description for more information. This feature is in development and not ready for general use.

func (DatabaseOptions) SetTransactionBypassUnreadable 

func (o DatabaseOptions) SetTransactionBypassUnreadable() error

Allows “get“ operations to read from sections of keyspace that have become unreadable because of versionstamp operations. This sets the “bypass_unreadable“ option of each transaction created by this database. See the transaction option description for more information.

func (DatabaseOptions) SetTransactionCausalReadRisky 

func (o DatabaseOptions) SetTransactionCausalReadRisky() error

The read version will be committed, and usually will be the latest committed, but might not be the latest committed in the event of a simultaneous fault and misbehaving clock.

func (DatabaseOptions) SetTransactionIncludePortInAddress 

func (o DatabaseOptions) SetTransactionIncludePortInAddress() error

Deprecated. Addresses returned by get_addresses_for_key include the port when enabled. As of api version 630, this option is enabled by default and setting this has no effect.

func (DatabaseOptions) SetTransactionLoggingMaxFieldLength 

func (o DatabaseOptions) SetTransactionLoggingMaxFieldLength(param int64) error

Sets the maximum escaped length of key and value fields to be logged to the trace file via the LOG_TRANSACTION option. This sets the “transaction_logging_max_field_length“ option of each transaction created by this database. See the transaction option description for more information.

Parameter: Maximum length of escaped key and value fields.

func (DatabaseOptions) SetTransactionMaxRetryDelay 

func (o DatabaseOptions) SetTransactionMaxRetryDelay(param int64) error

Set the maximum amount of backoff delay incurred in the call to “onError“ if the error is retryable. This sets the “max_retry_delay“ option of each transaction created by this database. See the transaction option description for more information.

Parameter: value in milliseconds of maximum delay

func (DatabaseOptions) SetTransactionReportConflictingKeys 

func (o DatabaseOptions) SetTransactionReportConflictingKeys() error

Enables conflicting key reporting on all transactions, allowing them to retrieve the keys that are conflicting with other transactions.

func (DatabaseOptions) SetTransactionRetryLimit 

func (o DatabaseOptions) SetTransactionRetryLimit(param int64) error

Set a maximum number of retries after which additional calls to “onError“ will throw the most recently seen error code. This sets the “retry_limit“ option of each transaction created by this database. See the transaction option description for more information.

Parameter: number of times to retry

func (DatabaseOptions) SetTransactionSizeLimit 

func (o DatabaseOptions) SetTransactionSizeLimit(param int64) error

Set the maximum transaction size in bytes. This sets the “size_limit“ option on each transaction created by this database. See the transaction option description for more information.

Parameter: value in bytes

func (DatabaseOptions) SetTransactionTimeout 

func (o DatabaseOptions) SetTransactionTimeout(param int64) error

Set a timeout in milliseconds which, when elapsed, will cause each transaction automatically to be cancelled. This sets the “timeout“ option of each transaction created by this database. See the transaction option description for more information. Using this option requires that the API version is 610 or higher.

Parameter: value in milliseconds of timeout

func (DatabaseOptions) SetTransactionUsedDuringCommitProtectionDisable 

func (o DatabaseOptions) SetTransactionUsedDuringCommitProtectionDisable() error

By default, operations that are performed on a transaction while it is being committed will not only fail themselves, but they will attempt to fail other in-flight operations (such as the commit) as well. This behavior is intended to help developers discover situations where operations could be unintentionally executed after the transaction has been reset. Setting this option removes that protection, causing only the offending operation to fail.

func (DatabaseOptions) SetUseConfigDatabase 

func (o DatabaseOptions) SetUseConfigDatabase() error

Use configuration database.

type Error 

type Error struct {
	Code int
}

Error represents a low-level error returned by the FoundationDB C library. An Error may be returned by any FoundationDB API function that returns error, or as a panic from any FoundationDB API function whose name ends with OrPanic.

You may compare the Code field of an Error against the list of FoundationDB error codes at https://apple.github.io/foundationdb/api-error-codes.html, but generally an Error should be passed to (Transaction).OnError. When using (Database).Transact, non-fatal errors will be retried automatically.

func (Error) Error 

func (e Error) Error() string

type ErrorPredicate 

type ErrorPredicate int
const (

	// Returns “true“ if the error indicates the operations in the transactions
	// should be retried because of transient error.
	ErrorPredicateRetryable ErrorPredicate = 50000

	// Returns “true“ if the error indicates the transaction may have succeeded,
	// though not in a way the system can verify.
	ErrorPredicateMaybeCommitted ErrorPredicate = 50001

	// Returns “true“ if the error indicates the transaction has not committed,
	// though in a way that can be retried.
	ErrorPredicateRetryableNotCommitted ErrorPredicate = 50002
)

type ExactRange 

type ExactRange interface {
	// FDBRangeKeys returns a pair of keys that describe the beginning and end
	// of a range.
	FDBRangeKeys() (begin, end KeyConvertible)

	// An object that implements ExactRange must also implement Range
	// (logically, by returning FirstGreaterOrEqual of the keys returned by
	// FDBRangeKeys).
	Range
}

An ExactRange describes all keys between a begin (inclusive) and end (exclusive) key. If you need to specify an ExactRange and you have only a Range, you must resolve the selectors returned by (Range).FDBRangeKeySelectors to keys using the (Transaction).GetKey method.

Any object that implements ExactRange also implements Range, and may be used accordingly.

type Future 

type Future interface {
	// BlockUntilReady blocks the calling goroutine until the future is ready. A
	// future becomes ready either when it receives a value of its enclosed type
	// (if any) or is set to an error state.
	BlockUntilReady()

	// IsReady returns true if the future is ready, and false otherwise, without
	// blocking. A future is ready either when has received a value of its
	// enclosed type (if any) or has been set to an error state.
	IsReady() bool

	// Cancel cancels a future and its associated asynchronous operation. If
	// called before the future becomes ready, attempts to access the future
	// will return an error. Cancel has no effect if the future is already
	// ready.
	//
	// Note that even if a future is not ready, the associated asynchronous
	// operation may already have completed and be unable to be cancelled.
	Cancel()
}

A Future represents a value (or error) to be available at some later time. Asynchronous FDB API functions return one of the types that implement the Future interface. All Future types additionally implement Get and MustGet methods with different return types. Calling BlockUntilReady, Get or MustGet will block the calling goroutine until the Future is ready.

type FutureByteSlice 

type FutureByteSlice interface {
	// Get returns a database value (or nil if there is no value), or an error
	// if the asynchronous operation associated with this future did not
	// successfully complete. The current goroutine will be blocked until the
	// future is ready.
	Get() ([]byte, error)

	// MustGet returns a database value (or nil if there is no value), or panics
	// if the asynchronous operation associated with this future did not
	// successfully complete. The current goroutine will be blocked until the
	// future is ready.
	MustGet() []byte

	Future
}

FutureByteSlice represents the asynchronous result of a function that returns a value from a database. FutureByteSlice is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

type FutureInt64 

type FutureInt64 interface {
	// Get returns a database version or an error if the asynchronous operation
	// associated with this future did not successfully complete. The current
	// goroutine will be blocked until the future is ready.
	Get() (int64, error)

	// MustGet returns a database version, or panics if the asynchronous
	// operation associated with this future did not successfully complete. The
	// current goroutine will be blocked until the future is ready.
	MustGet() int64

	Future
}

FutureInt64 represents the asynchronous result of a function that returns a database version. FutureInt64 is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

type FutureKey 

type FutureKey interface {
	// Get returns a database key or an error if the asynchronous operation
	// associated with this future did not successfully complete. The current
	// goroutine will be blocked until the future is ready.
	Get() (Key, error)

	// MustGet returns a database key, or panics if the asynchronous operation
	// associated with this future did not successfully complete. The current
	// goroutine will be blocked until the future is ready.
	MustGet() Key

	Future
}

FutureKey represents the asynchronous result of a function that returns a key from a database. FutureKey is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

type FutureKeyArray 

type FutureKeyArray interface {

	// Get returns an array of keys or an error if the asynchronous operation
	// associated with this future did not successfully complete. The current
	// goroutine will be blocked until the future is ready.
	Get() ([]Key, error)

	// MustGet returns an array of keys, or panics if the asynchronous operations
	// associated with this future did not successfully complete. The current goroutine
	// will be blocked until the future is ready.
	MustGet() []Key
}

FutureKeyArray represents the asynchronous result of a function that returns an array of keys. FutureKeyArray is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

type FutureNil 

type FutureNil interface {
	// Get returns an error if the asynchronous operation associated with this
	// future did not successfully complete. The current goroutine will be
	// blocked until the future is ready.
	Get() error

	// MustGet panics if the asynchronous operation associated with this future
	// did not successfully complete. The current goroutine will be blocked
	// until the future is ready.
	MustGet()

	Future
}

FutureNil represents the asynchronous result of a function that has no return value. FutureNil is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

type FutureStringSlice 

type FutureStringSlice interface {
	// Get returns a slice of strings or an error if the asynchronous operation
	// associated with this future did not successfully complete. The current
	// goroutine will be blocked until the future is ready.
	Get() ([]string, error)

	// MustGet returns a slice of strings or panics if the asynchronous
	// operation associated with this future did not successfully complete. The
	// current goroutine will be blocked until the future is ready.
	MustGet() []string

	Future
}

FutureStringSlice represents the asynchronous result of a function that returns a slice of strings. FutureStringSlice is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

type Key 

type Key []byte

Key represents a FoundationDB key, a lexicographically-ordered sequence of bytes. Key implements the KeyConvertible interface.

func (Key) FDBKey 

func (k Key) FDBKey() Key

FDBKey allows Key to (trivially) satisfy the KeyConvertible interface.

func (Key) String 

func (k Key) String() string

String describes the key as a human readable string.

type KeyConvertible 

type KeyConvertible interface {
	FDBKey() Key
}

A KeyConvertible can be converted to a FoundationDB Key. All functions in the FoundationDB API that address a specific key accept a KeyConvertible.

type KeyRange 

type KeyRange struct {
	// The (inclusive) beginning of the range
	Begin KeyConvertible

	// The (exclusive) end of the range
	End KeyConvertible
}

KeyRange is an ExactRange constructed from a pair of KeyConvertibles. Note that the default zero-value of KeyRange specifies an empty range before all keys in the database.

func PrefixRange 

func PrefixRange(prefix []byte) (KeyRange, error)

PrefixRange returns the KeyRange describing the range of keys k such that bytes.HasPrefix(k, prefix) is true. PrefixRange returns an error if prefix is empty or entirely 0xFF bytes.

Do not use PrefixRange on objects that already implement the Range or ExactRange interfaces. The prefix range of the byte representation of these objects may not correspond to their logical range.

Example 
package main

import (
	"fmt"

	"github.com/apple/foundationdb/bindings/go/src/fdb"
)

const API_VERSION int = 740

func main() {
	fdb.MustAPIVersion(API_VERSION)
	db := fdb.MustOpenDefault()

	tr, e := db.CreateTransaction()
	if e != nil {
		fmt.Printf("Unable to create transaction: %v\n", e)
		return
	}

	// Clear and initialize data in this transaction. In examples we do not
	// commit transactions to avoid mutating a real database.
	tr.ClearRange(fdb.KeyRange{fdb.Key(""), fdb.Key{0xFF}})
	tr.Set(fdb.Key("alpha"), []byte("1"))
	tr.Set(fdb.Key("alphabetA"), []byte("2"))
	tr.Set(fdb.Key("alphabetB"), []byte("3"))
	tr.Set(fdb.Key("alphabetize"), []byte("4"))
	tr.Set(fdb.Key("beta"), []byte("5"))

	// Construct the range of all keys beginning with "alphabet". It is safe to
	// ignore the error return from PrefixRange unless the provided prefix might
	// consist entirely of zero or more 0xFF bytes.
	pr, _ := fdb.PrefixRange([]byte("alphabet"))

	// Read and process the range
	kvs, e := tr.GetRange(pr, fdb.RangeOptions{}).GetSliceWithError()
	if e != nil {
		fmt.Printf("Unable to read range: %v\n", e)
	}
	for _, kv := range kvs {
		fmt.Printf("%s: %s\n", string(kv.Key), string(kv.Value))
	}

}

Output:

alphabetA: 2
alphabetB: 3
alphabetize: 4

func (KeyRange) FDBRangeKeySelectors 

func (kr KeyRange) FDBRangeKeySelectors() (Selectable, Selectable)

FDBRangeKeySelectors allows KeyRange to satisfy the Range interface.

func (KeyRange) FDBRangeKeys 

func (kr KeyRange) FDBRangeKeys() (KeyConvertible, KeyConvertible)

FDBRangeKeys allows KeyRange to satisfy the ExactRange interface.

type KeySelector 

type KeySelector struct {
	Key     KeyConvertible
	OrEqual bool
	Offset  int
}

KeySelector represents a description of a key in a FoundationDB database. A KeySelector may be resolved to a specific key with the GetKey method, or used as the endpoints of a SelectorRange to be used with a GetRange function.

The most common key selectors are constructed with the functions documented below. For details of how KeySelectors are specified and resolved, see https://apple.github.io/foundationdb/developer-guide.html#key-selectors.

func FirstGreaterOrEqual 

func FirstGreaterOrEqual(key KeyConvertible) KeySelector

FirstGreaterOrEqual returns the KeySelector specifying the lexicographically least key present in the database which is lexicographically greater than or equal to the given key.

func FirstGreaterThan 

func FirstGreaterThan(key KeyConvertible) KeySelector

FirstGreaterThan returns the KeySelector specifying the lexicographically least key present in the database which is lexicographically strictly greater than the given key.

func LastLessOrEqual 

func LastLessOrEqual(key KeyConvertible) KeySelector

LastLessOrEqual returns the KeySelector specifying the lexicographically greatest key present in the database which is lexicographically less than or equal to the given key.

func LastLessThan 

func LastLessThan(key KeyConvertible) KeySelector

LastLessThan returns the KeySelector specifying the lexicographically greatest key present in the database which is lexicographically strictly less than the given key.

func (KeySelector) FDBKeySelector 

func (ks KeySelector) FDBKeySelector() KeySelector

type KeyValue 

type KeyValue struct {
	Key   Key
	Value []byte
}

KeyValue represents a single key-value pair in the database.

type NetworkOptions 

type NetworkOptions struct {
}

NetworkOptions is a handle with which to set options that affect the entire FoundationDB client. A NetworkOptions instance should be obtained with the fdb.Options function.

func Options 

func Options() NetworkOptions

Options returns a NetworkOptions instance suitable for setting options that affect the entire FoundationDB client.

func (NetworkOptions) SetBuggifyDisable 

func (o NetworkOptions) SetBuggifyDisable() error

Not yet implemented.

func (NetworkOptions) SetBuggifyEnable 

func (o NetworkOptions) SetBuggifyEnable() error

Not yet implemented.

func (NetworkOptions) SetBuggifySectionActivatedProbability 

func (o NetworkOptions) SetBuggifySectionActivatedProbability(param int64) error

Set the probability of a BUGGIFY section being active for the current execution. Only applies to code paths first traversed AFTER this option is changed.

Parameter: probability expressed as a percentage between 0 and 100

func (NetworkOptions) SetBuggifySectionFiredProbability 

func (o NetworkOptions) SetBuggifySectionFiredProbability(param int64) error

Set the probability of an active BUGGIFY section being fired

Parameter: probability expressed as a percentage between 0 and 100

func (NetworkOptions) SetCallbacksOnExternalThreads 

func (o NetworkOptions) SetCallbacksOnExternalThreads() error

If set, callbacks from external client libraries can be called from threads created by the FoundationDB client library. Otherwise, callbacks will be called from either the thread used to add the callback or the network thread. Setting this option can improve performance when connected using an external client, but may not be safe to use in all environments. Must be set before setting up the network. WARNING: This feature is considered experimental at this time.

func (NetworkOptions) SetClientBuggifyDisable 

func (o NetworkOptions) SetClientBuggifyDisable() error

Disable client buggify

func (NetworkOptions) SetClientBuggifyEnable 

func (o NetworkOptions) SetClientBuggifyEnable() error

Enable client buggify - will make requests randomly fail (intended for client testing)

func (NetworkOptions) SetClientBuggifySectionActivatedProbability 

func (o NetworkOptions) SetClientBuggifySectionActivatedProbability(param int64) error

Set the probability of a CLIENT_BUGGIFY section being active for the current execution.

Parameter: probability expressed as a percentage between 0 and 100

func (NetworkOptions) SetClientBuggifySectionFiredProbability 

func (o NetworkOptions) SetClientBuggifySectionFiredProbability(param int64) error

Set the probability of an active CLIENT_BUGGIFY section being fired. A section will only fire if it was activated

Parameter: probability expressed as a percentage between 0 and 100

func (NetworkOptions) SetClientThreadsPerVersion 

func (o NetworkOptions) SetClientThreadsPerVersion(param int64) error

Spawns multiple worker threads for each version of the client that is loaded. Setting this to a number greater than one implies disable_local_client.

Parameter: Number of client threads to be spawned. Each cluster will be serviced by a single client thread.

func (NetworkOptions) SetClientTmpDir 

func (o NetworkOptions) SetClientTmpDir(param string) error

Sets the directory for storing temporary files created by FDB client, such as temporary copies of client libraries. Defaults to /tmp

Parameter: Client directory for temporary files.

func (NetworkOptions) SetClusterFile 

func (o NetworkOptions) SetClusterFile(param string) error

Deprecated

Parameter: path to cluster file

func (NetworkOptions) SetDisableClientBypass 

func (o NetworkOptions) SetDisableClientBypass() error

Prevents the multi-version client API from being disabled, even if no external clients are configured. This option is required to use GRV caching.

func (NetworkOptions) SetDisableClientStatisticsLogging 

func (o NetworkOptions) SetDisableClientStatisticsLogging() error

Disables logging of client statistics, such as sampled transaction activity.

func (NetworkOptions) SetDisableLocalClient 

func (o NetworkOptions) SetDisableLocalClient() error

Prevents connections through the local client, allowing only connections through externally loaded client libraries.

func (NetworkOptions) SetDisableMultiVersionClientApi 

func (o NetworkOptions) SetDisableMultiVersionClientApi() error

Disables the multi-version client API and instead uses the local client directly. Must be set before setting up the network.

func (NetworkOptions) SetDistributedClientTracer 

func (o NetworkOptions) SetDistributedClientTracer(param string) error

Set a tracer to run on the client. Should be set to the same value as the tracer set on the server.

Parameter: Distributed tracer type. Choose from none, log_file, or network_lossy

func (NetworkOptions) SetEnableRunLoopProfiling 

func (o NetworkOptions) SetEnableRunLoopProfiling() error

Enables debugging feature to perform run loop profiling. Requires trace logging to be enabled. WARNING: this feature is not recommended for use in production.

func (NetworkOptions) SetEnableSlowTaskProfiling 

func (o NetworkOptions) SetEnableSlowTaskProfiling() error

Deprecated

func (NetworkOptions) SetExternalClientDirectory 

func (o NetworkOptions) SetExternalClientDirectory(param string) error

Searches the specified path for dynamic libraries and adds them to the list of client libraries for use by the multi-version client API. Must be set before setting up the network.

Parameter: path to directory containing client libraries

func (NetworkOptions) SetExternalClientLibrary 

func (o NetworkOptions) SetExternalClientLibrary(param string) error

Adds an external client library for use by the multi-version client API. Must be set before setting up the network.

Parameter: path to client library

func (NetworkOptions) SetFailIncompatibleClient 

func (o NetworkOptions) SetFailIncompatibleClient() error

Fail with an error if there is no client matching the server version the client is connecting to

func (NetworkOptions) SetFutureVersionClientLibrary 

func (o NetworkOptions) SetFutureVersionClientLibrary(param string) error

Adds an external client library to be used with a future version protocol. This option can be used testing purposes only!

Parameter: path to client library

func (NetworkOptions) SetIgnoreExternalClientFailures 

func (o NetworkOptions) SetIgnoreExternalClientFailures() error

Ignore the failure to initialize some of the external clients

func (NetworkOptions) SetKnob 

func (o NetworkOptions) SetKnob(param string) error

Set internal tuning or debugging knobs

Parameter: knob_name=knob_value

func (NetworkOptions) SetLocalAddress 

func (o NetworkOptions) SetLocalAddress(param string) error

Deprecated

Parameter: IP:PORT

func (NetworkOptions) SetRetainClientLibraryCopies 

func (o NetworkOptions) SetRetainClientLibraryCopies() error

Retain temporary external client library copies that are created for enabling multi-threading.

func (NetworkOptions) SetTLSCaBytes 

func (o NetworkOptions) SetTLSCaBytes(param []byte) error

Set the ca bundle

Parameter: ca bundle

func (NetworkOptions) SetTLSCaPath 

func (o NetworkOptions) SetTLSCaPath(param string) error

Set the file from which to load the certificate authority bundle

Parameter: file path

func (NetworkOptions) SetTLSCertBytes 

func (o NetworkOptions) SetTLSCertBytes(param []byte) error

Set the certificate chain

Parameter: certificates

func (NetworkOptions) SetTLSCertPath 

func (o NetworkOptions) SetTLSCertPath(param string) error

Set the file from which to load the certificate chain

Parameter: file path

func (NetworkOptions) SetTLSDisablePlaintextConnection 

func (o NetworkOptions) SetTLSDisablePlaintextConnection() error

Prevent client from connecting to a non-TLS endpoint by throwing network connection failed error.

func (NetworkOptions) SetTLSKeyBytes 

func (o NetworkOptions) SetTLSKeyBytes(param []byte) error

Set the private key corresponding to your own certificate

Parameter: key

func (NetworkOptions) SetTLSKeyPath 

func (o NetworkOptions) SetTLSKeyPath(param string) error

Set the file from which to load the private key corresponding to your own certificate

Parameter: file path

func (NetworkOptions) SetTLSPassword 

func (o NetworkOptions) SetTLSPassword(param string) error

Set the passphrase for encrypted private key. Password should be set before setting the key for the password to be used.

Parameter: key passphrase

func (NetworkOptions) SetTLSPlugin 

func (o NetworkOptions) SetTLSPlugin(param string) error

Deprecated

Parameter: file path or linker-resolved name

func (NetworkOptions) SetTLSVerifyPeers 

func (o NetworkOptions) SetTLSVerifyPeers(param []byte) error

Set the peer certificate field verification criteria

Parameter: verification pattern

func (NetworkOptions) SetTraceClockSource 

func (o NetworkOptions) SetTraceClockSource(param string) error

Select clock source for trace files. now (the default) or realtime are supported.

Parameter: Trace clock source

func (NetworkOptions) SetTraceEnable 

func (o NetworkOptions) SetTraceEnable(param string) error

Enables trace output to a file in a directory of the clients choosing

Parameter: path to output directory (or NULL for current working directory)

func (NetworkOptions) SetTraceFileIdentifier 

func (o NetworkOptions) SetTraceFileIdentifier(param string) error

Once provided, this string will be used to replace the port/PID in the log file names.

Parameter: The identifier that will be part of all trace file names

func (NetworkOptions) SetTraceFormat 

func (o NetworkOptions) SetTraceFormat(param string) error

Select the format of the log files. xml (the default) and json are supported.

Parameter: Format of trace files

func (NetworkOptions) SetTraceInitializeOnSetup 

func (o NetworkOptions) SetTraceInitializeOnSetup() error

Initialize trace files on network setup, determine the local IP later. Otherwise tracing is initialized when opening the first database.

func (NetworkOptions) SetTraceLogGroup 

func (o NetworkOptions) SetTraceLogGroup(param string) error

Sets the 'LogGroup' attribute with the specified value for all events in the trace output files. The default log group is 'default'.

Parameter: value of the LogGroup attribute

func (NetworkOptions) SetTraceMaxLogsSize 

func (o NetworkOptions) SetTraceMaxLogsSize(param int64) error

Sets the maximum size of all the trace output files put together. This value should be in the range “[0, INT64_MAX]“. If the value is set to 0, there is no limit on the total size of the files. The default is a maximum size of 104,857,600 bytes. If the default roll size is used, this means that a maximum of 10 trace files will be written at a time.

Parameter: max total size of trace files

func (NetworkOptions) SetTracePartialFileSuffix 

func (o NetworkOptions) SetTracePartialFileSuffix(param string) error

Set file suffix for partially written log files.

Parameter: Append this suffix to partially written log files. When a log file is complete, it is renamed to remove the suffix. No separator is added between the file and the suffix. If you want to add a file extension, you should include the separator - e.g. '.tmp' instead of 'tmp' to add the 'tmp' extension.

func (NetworkOptions) SetTraceRollSize 

func (o NetworkOptions) SetTraceRollSize(param int64) error

Sets the maximum size in bytes of a single trace output file. This value should be in the range “[0, INT64_MAX]“. If the value is set to 0, there is no limit on individual file size. The default is a maximum size of 10,485,760 bytes.

Parameter: max size of a single trace output file

func (NetworkOptions) SetTraceShareAmongClientThreads 

func (o NetworkOptions) SetTraceShareAmongClientThreads() error

Use the same base trace file name for all client threads as it did before version 7.2. The current default behavior is to use distinct trace file names for client threads by including their version and thread index.

type Range 

type Range interface {
	// FDBRangeKeySelectors returns a pair of key selectors that describe the
	// beginning and end of a range.
	FDBRangeKeySelectors() (begin, end Selectable)
}

A Range describes all keys between a begin (inclusive) and end (exclusive) key selector.

type RangeIterator 

type RangeIterator struct {
	// contains filtered or unexported fields
}

RangeIterator returns the key-value pairs in the database (as KeyValue objects) satisfying the range specified in a range read. RangeIterator is constructed with the (RangeResult).Iterator method.

You must call Advance and get a true result prior to calling Get or MustGet.

RangeIterator should not be copied or used concurrently from multiple goroutines, but multiple RangeIterators may be constructed from a single RangeResult and used concurrently. RangeIterator should not be returned from a transactional function passed to the Transact method of a Transactor.

Example 
package main

import (
	"fmt"

	"github.com/apple/foundationdb/bindings/go/src/fdb"
)

const API_VERSION int = 740

func main() {
	fdb.MustAPIVersion(API_VERSION)
	db := fdb.MustOpenDefault()

	tr, e := db.CreateTransaction()
	if e != nil {
		fmt.Printf("Unable to create transaction: %v\n", e)
		return
	}

	// Clear and initialize data in this transaction. In examples we do not
	// commit transactions to avoid mutating a real database.
	tr.ClearRange(fdb.KeyRange{fdb.Key(""), fdb.Key{0xFF}})
	tr.Set(fdb.Key("apple"), []byte("foo"))
	tr.Set(fdb.Key("cherry"), []byte("baz"))
	tr.Set(fdb.Key("banana"), []byte("bar"))

	rr := tr.GetRange(fdb.KeyRange{fdb.Key(""), fdb.Key{0xFF}}, fdb.RangeOptions{})
	ri := rr.Iterator()

	// Advance will return true until the iterator is exhausted
	for ri.Advance() {
		kv, e := ri.Get()
		if e != nil {
			fmt.Printf("Unable to read next value: %v\n", e)
			return
		}
		fmt.Printf("%s is %s\n", kv.Key, kv.Value)
	}

}

Output:

apple is foo
banana is bar
cherry is baz

func (*RangeIterator) Advance 

func (ri *RangeIterator) Advance() bool

Advance attempts to advance the iterator to the next key-value pair. Advance returns true if there are more key-value pairs satisfying the range, or false if the range has been exhausted. You must call this before every call to Get or MustGet.

func (*RangeIterator) Get 

func (ri *RangeIterator) Get() (kv KeyValue, e error)

Get returns the next KeyValue in a range read, or an error if one of the asynchronous operations associated with this range did not successfully complete. The Advance method of this RangeIterator must have returned true prior to calling Get.

func (*RangeIterator) MustGet 

func (ri *RangeIterator) MustGet() KeyValue

MustGet returns the next KeyValue in a range read, or panics if one of the asynchronous operations associated with this range did not successfully complete. The Advance method of this RangeIterator must have returned true prior to calling MustGet.

type RangeOptions 

type RangeOptions struct {
	// Limit restricts the number of key-value pairs returned as part of a range
	// read. A value of 0 indicates no limit.
	Limit int

	// Mode sets the streaming mode of the range read, allowing the database to
	// balance latency and bandwidth for this read.
	Mode StreamingMode

	// Reverse indicates that the read should be performed in lexicographic
	// (false) or reverse lexicographic (true) order. When Reverse is true and
	// Limit is non-zero, the last Limit key-value pairs in the range are
	// returned. Reading ranges in reverse is supported natively by the
	// database and should have minimal extra cost.
	Reverse bool
}

RangeOptions specify how a database range read operation is carried out. RangeOptions objects are passed to GetRange methods of Database, Transaction and Snapshot.

The zero value of RangeOptions represents the default range read configuration (no limit, lexicographic order, to be used as an iterator).

type RangeResult 

type RangeResult struct {
	// contains filtered or unexported fields
}

RangeResult is a handle to the asynchronous result of a range read. RangeResult is safe for concurrent use by multiple goroutines.

A RangeResult should not be returned from a transactional function passed to the Transact method of a Transactor.

func (RangeResult) GetSliceOrPanic 

func (rr RangeResult) GetSliceOrPanic() []KeyValue

GetSliceOrPanic returns a slice of KeyValue objects satisfying the range specified in the read that returned this RangeResult, or panics if any of the asynchronous operations associated with this result did not successfully complete. The current goroutine will be blocked until all reads have completed.

func (RangeResult) GetSliceWithError 

func (rr RangeResult) GetSliceWithError() ([]KeyValue, error)

GetSliceWithError returns a slice of KeyValue objects satisfying the range specified in the read that returned this RangeResult, or an error if any of the asynchronous operations associated with this result did not successfully complete. The current goroutine will be blocked until all reads have completed.

func (RangeResult) Iterator 

func (rr RangeResult) Iterator() *RangeIterator

Iterator returns a RangeIterator over the key-value pairs satisfying the range specified in the read that returned this RangeResult.

type ReadTransaction 

type ReadTransaction interface {
	Get(key KeyConvertible) FutureByteSlice
	GetKey(sel Selectable) FutureKey
	GetRange(r Range, options RangeOptions) RangeResult
	GetReadVersion() FutureInt64
	GetDatabase() Database
	Snapshot() Snapshot
	GetEstimatedRangeSizeBytes(r ExactRange) FutureInt64
	GetRangeSplitPoints(r ExactRange, chunkSize int64) FutureKeyArray
	Options() TransactionOptions
	Cancel()

	ReadTransactor
}

A ReadTransaction can asynchronously read from a FoundationDB database. Transaction and Snapshot both satisfy the ReadTransaction interface.

All ReadTransactions satisfy the ReadTransactor interface and may be used with read-only transactional functions.

type ReadTransactor 

type ReadTransactor interface {
	// ReadTransact executes the caller-provided function, providing it with a
	// ReadTransaction (itself a ReadTransactor, allowing composition of
	// read-only transactional functions).
	ReadTransact(func(ReadTransaction) (interface{}, error)) (interface{}, error)
}

A ReadTransactor can execute a function that requires a ReadTransaction. Functions written to accept a ReadTransactor are called read-only transactional functions, and may be called with a Database, Transaction or Snapshot.

Example 
package main

import (
	"fmt"

	"github.com/apple/foundationdb/bindings/go/src/fdb"
)

const API_VERSION int = 740

func main() {
	fdb.MustAPIVersion(API_VERSION)
	db := fdb.MustOpenDefault()

	getOne := func(rt fdb.ReadTransactor, key fdb.Key) ([]byte, error) {
		fmt.Printf("getOne called with: %T\n", rt)
		ret, e := rt.ReadTransact(func(rtr fdb.ReadTransaction) (interface{}, error) {
			return rtr.Get(key).MustGet(), nil
		})
		if e != nil {
			return nil, e
		}
		return ret.([]byte), nil
	}

	getTwo := func(rt fdb.ReadTransactor, key1, key2 fdb.Key) ([][]byte, error) {
		fmt.Printf("getTwo called with: %T\n", rt)
		ret, e := rt.ReadTransact(func(rtr fdb.ReadTransaction) (interface{}, error) {
			r1, _ := getOne(rtr, key1)
			r2, _ := getOne(rtr.Snapshot(), key2)
			return [][]byte{r1, r2}, nil
		})
		if e != nil {
			return nil, e
		}
		return ret.([][]byte), nil
	}

	var e error

	fmt.Println("Calling getOne with a database:")
	_, e = getOne(db, fdb.Key("foo"))
	if e != nil {
		fmt.Println(e)
		return
	}
	fmt.Println("\nCalling getTwo with a database:")
	_, e = getTwo(db, fdb.Key("foo"), fdb.Key("bar"))
	if e != nil {
		fmt.Println(e)
		return
	}

}

Output:

Calling getOne with a database:
getOne called with: fdb.Database

Calling getTwo with a database:
getTwo called with: fdb.Database
getOne called with: fdb.Transaction
getOne called with: fdb.Snapshot

type Selectable 

type Selectable interface {
	FDBKeySelector() KeySelector
}

A Selectable can be converted to a FoundationDB KeySelector. All functions in the FoundationDB API that resolve a key selector to a key accept Selectable.

type SelectorRange 

type SelectorRange struct {
	Begin, End Selectable
}

SelectorRange is a Range constructed directly from a pair of Selectable objects. Note that the default zero-value of SelectorRange specifies an empty range before all keys in the database.

func (SelectorRange) FDBRangeKeySelectors 

func (sr SelectorRange) FDBRangeKeySelectors() (Selectable, Selectable)

FDBRangeKeySelectors allows SelectorRange to satisfy the Range interface.

type Snapshot 

type Snapshot struct {
	// contains filtered or unexported fields
}

Snapshot is a handle to a FoundationDB transaction snapshot, suitable for performing snapshot reads. Snapshot reads offer a more relaxed isolation level than FoundationDB's default serializable isolation, reducing transaction conflicts but making it harder to reason about concurrency.

For more information on snapshot reads, see https://apple.github.io/foundationdb/developer-guide.html#snapshot-reads.

func (Snapshot) Cancel 

func (s Snapshot) Cancel()

Cancel cancels the underlying transaction of the snapshot. See Transaction.Cancel() for more information.

func (Snapshot) Get 

func (s Snapshot) Get(key KeyConvertible) FutureByteSlice

Get is equivalent to (Transaction).Get, performed as a snapshot read.

func (Snapshot) GetDatabase 

func (s Snapshot) GetDatabase() Database

GetDatabase returns a handle to the database with which this snapshot is interacting.

func (Snapshot) GetEstimatedRangeSizeBytes 

func (s Snapshot) GetEstimatedRangeSizeBytes(r ExactRange) FutureInt64

GetEstimatedRangeSizeBytes returns an estimate for the number of bytes stored in the given range.

func (Snapshot) GetKey 

func (s Snapshot) GetKey(sel Selectable) FutureKey

GetKey is equivalent to (Transaction).GetKey, performed as a snapshot read.

func (Snapshot) GetRange 

func (s Snapshot) GetRange(r Range, options RangeOptions) RangeResult

GetRange is equivalent to (Transaction).GetRange, performed as a snapshot read.

func (Snapshot) GetRangeSplitPoints 

func (s Snapshot) GetRangeSplitPoints(r ExactRange, chunkSize int64) FutureKeyArray

GetRangeSplitPoints returns a list of keys that can split the given range into (roughly) equally sized chunks based on chunkSize. Note: the returned split points contain the start key and end key of the given range.

func (Snapshot) GetReadVersion 

func (s Snapshot) GetReadVersion() FutureInt64

GetReadVersion is equivalent to (Transaction).GetReadVersion, performed as a snapshot read.

func (Snapshot) Options 

func (s Snapshot) Options() TransactionOptions

Snapshot returns the receiver and allows Snapshot to satisfy the ReadTransaction interface.

func (Snapshot) ReadTransact 

func (s Snapshot) ReadTransact(f func(ReadTransaction) (interface{}, error)) (r interface{}, e error)

ReadTransact executes the caller-provided function, passing it the Snapshot receiver object (as a ReadTransaction).

A panic of type Error during execution of the function will be recovered and returned to the caller as an error, but ReadTransact will not retry the function.

By satisfying the ReadTransactor interface, Snapshot may be passed to a read-only transactional function from another (possibly read-only) transactional function, allowing composition.

See the ReadTransactor interface for an example of using ReadTransact with Transaction, Snapshot and Database objects.

func (Snapshot) Snapshot 

func (s Snapshot) Snapshot() Snapshot

Snapshot returns the receiver and allows Snapshot to satisfy the ReadTransaction interface.

type StreamingMode 

type StreamingMode int
const (

	// Client intends to consume the entire range and would like it all
	// transferred as early as possible.
	StreamingModeWantAll StreamingMode = -1

	// The default. The client doesn't know how much of the range it is likely
	// to used and wants different performance concerns to be balanced.
	// Only a small portion of data is transferred to the client initially (in
	// order to minimize costs if the client doesn't read the entire range), and
	// as the caller iterates over more items in the range larger batches will
	// be transferred in order to minimize latency. After enough iterations,
	// the iterator mode will eventually reach the same byte limit as “WANT_ALL“
	StreamingModeIterator StreamingMode = 0

	// Infrequently used. The client has passed a specific row limit and wants
	// that many rows delivered in a single batch. Because of iterator operation
	// in client drivers make request batches transparent to the user, consider
	// “WANT_ALL“ StreamingMode instead. A row limit must be specified if this
	// mode is used.
	StreamingModeExact StreamingMode = 1

	// Infrequently used. Transfer data in batches small enough to not be
	// much more expensive than reading individual rows, to minimize cost if
	// iteration stops early.
	StreamingModeSmall StreamingMode = 2

	// Infrequently used. Transfer data in batches sized in between small and
	// large.
	StreamingModeMedium StreamingMode = 3

	// Infrequently used. Transfer data in batches large enough to be,
	// in a high-concurrency environment, nearly as efficient as possible.
	// If the client stops iteration early, some disk and network bandwidth may
	// be wasted. The batch size may still be too small to allow a single client
	// to get high throughput from the database, so if that is what you need
	// consider the SERIAL StreamingMode.
	StreamingModeLarge StreamingMode = 4

	// Transfer data in batches large enough that an individual client can
	// get reasonable read bandwidth from the database. If the client stops
	// iteration early, considerable disk and network bandwidth may be wasted.
	StreamingModeSerial StreamingMode = 5
)

type Transaction 

type Transaction struct {
	// contains filtered or unexported fields
}

Transaction is a handle to a FoundationDB transaction. Transaction is a lightweight object that may be efficiently copied, and is safe for concurrent use by multiple goroutines.

In FoundationDB, a transaction is a mutable snapshot of a database. All read and write operations on a transaction see and modify an otherwise-unchanging version of the database and only change the underlying database if and when the transaction is committed. Read operations do see the effects of previous write operations on the same transaction. Committing a transaction usually succeeds in the absence of conflicts.

Transactions group operations into a unit with the properties of atomicity, isolation, and durability. Transactions also provide the ability to maintain an applications invariants or integrity constraints, supporting the property of consistency. Together these properties are known as ACID.

Transactions are also causally consistent: once a transaction has been successfully committed, all subsequently created transactions will see the modifications made by it.

func (Transaction) Add 

func (t Transaction) Add(key KeyConvertible, param []byte)

Performs an addition of little-endian integers. If the existing value in the database is not present or shorter than “param“, it is first extended to the length of “param“ with zero bytes. If “param“ is shorter than the existing value in the database, the existing value is truncated to match the length of “param“. The integers to be added must be stored in a little-endian representation. They can be signed in two's complement representation or unsigned. You can add to an integer at a known offset in the value by prepending the appropriate number of zero bytes to “param“ and padding with zero bytes to match the length of the value. However, this offset technique requires that you know the addition will not cause the integer field within the value to overflow.

func (Transaction) AddReadConflictKey 

func (t Transaction) AddReadConflictKey(key KeyConvertible) error

AddReadConflictKey adds a key to the transactions read conflict ranges as if you had read the key. As a result, other transactions that concurrently write this key could cause the transaction to fail with a conflict.

For more information on conflict ranges, see https://apple.github.io/foundationdb/developer-guide.html#conflict-ranges.

func (Transaction) AddReadConflictRange 

func (t Transaction) AddReadConflictRange(er ExactRange) error

AddReadConflictRange adds a range of keys to the transactions read conflict ranges as if you had read the range. As a result, other transactions that write a key in this range could cause the transaction to fail with a conflict.

For more information on conflict ranges, see https://apple.github.io/foundationdb/developer-guide.html#conflict-ranges.

func (Transaction) AddWriteConflictKey 

func (t Transaction) AddWriteConflictKey(key KeyConvertible) error

AddWriteConflictKey adds a key to the transactions write conflict ranges as if you had written the key. As a result, other transactions that concurrently read this key could fail with a conflict.

For more information on conflict ranges, see https://apple.github.io/foundationdb/developer-guide.html#conflict-ranges.

func (Transaction) AddWriteConflictRange 

func (t Transaction) AddWriteConflictRange(er ExactRange) error

AddWriteConflictRange adds a range of keys to the transactions write conflict ranges as if you had cleared the range. As a result, other transactions that concurrently read a key in this range could fail with a conflict.

For more information on conflict ranges, see https://apple.github.io/foundationdb/developer-guide.html#conflict-ranges.

func (Transaction) And 

func (t Transaction) And(key KeyConvertible, param []byte)

Deprecated

func (Transaction) AppendIfFits 

func (t Transaction) AppendIfFits(key KeyConvertible, param []byte)

Appends “param“ to the end of the existing value already in the database at the given key (or creates the key and sets the value to “param“ if the key is empty). This will only append the value if the final concatenated value size is less than or equal to the maximum value size (i.e., if it fits). WARNING: No error is surfaced back to the user if the final value is too large because the mutation will not be applied until after the transaction has been committed. Therefore, it is only safe to use this mutation type if one can guarantee that one will keep the total value size under the maximum size.

func (Transaction) BitAnd 

func (t Transaction) BitAnd(key KeyConvertible, param []byte)

Performs a bitwise “and“ operation. If the existing value in the database is not present, then “param“ is stored in the database. If the existing value in the database is shorter than “param“, it is first extended to the length of “param“ with zero bytes. If “param“ is shorter than the existing value in the database, the existing value is truncated to match the length of “param“.

func (Transaction) BitOr 

func (t Transaction) BitOr(key KeyConvertible, param []byte)

Performs a bitwise “or“ operation. If the existing value in the database is not present or shorter than “param“, it is first extended to the length of “param“ with zero bytes. If “param“ is shorter than the existing value in the database, the existing value is truncated to match the length of “param“.

func (Transaction) BitXor 

func (t Transaction) BitXor(key KeyConvertible, param []byte)

Performs a bitwise “xor“ operation. If the existing value in the database is not present or shorter than “param“, it is first extended to the length of “param“ with zero bytes. If “param“ is shorter than the existing value in the database, the existing value is truncated to match the length of “param“.

func (Transaction) ByteMax 

func (t Transaction) ByteMax(key KeyConvertible, param []byte)

Performs lexicographic comparison of byte strings. If the existing value in the database is not present, then “param“ is stored. Otherwise the larger of the two values is then stored in the database.

func (Transaction) ByteMin 

func (t Transaction) ByteMin(key KeyConvertible, param []byte)

Performs lexicographic comparison of byte strings. If the existing value in the database is not present, then “param“ is stored. Otherwise the smaller of the two values is then stored in the database.

func (Transaction) Cancel 

func (t Transaction) Cancel()

Cancel cancels a transaction. All pending or future uses of the transaction will encounter an error. The Transaction object may be reused after calling (Transaction).Reset.

Be careful if you are using (Transaction).Reset and (Transaction).Cancel concurrently with the same transaction. Since they negate each others effects, a race condition between these calls will leave the transaction in an unknown state.

If your program attempts to cancel a transaction after (Transaction).Commit has been called but before it returns, unpredictable behavior will result. While it is guaranteed that the transaction will eventually end up in a cancelled state, the commit may or may not occur. Moreover, even if the call to (Transaction).Commit appears to return a transaction_cancelled error, the commit may have occurred or may occur in the future. This can make it more difficult to reason about the order in which transactions occur.

func (Transaction) Clear 

func (t Transaction) Clear(key KeyConvertible)

Clear removes the specified key (and any associated value), if it exists. Clear returns immediately, having modified the snapshot of the database represented by the transaction.

func (Transaction) ClearRange 

func (t Transaction) ClearRange(er ExactRange)

ClearRange removes all keys k such that begin <= k < end, and their associated values. ClearRange returns immediately, having modified the snapshot of the database represented by the transaction. Range clears are efficient with FoundationDB -- clearing large amounts of data will be fast. However, this will not immediately free up disk - data for the deleted range is cleaned up in the background. For purposes of computing the transaction size, only the begin and end keys of a clear range are counted. The size of the data stored in the range does not count against the transaction size limit.

func (Transaction) Commit 

func (t Transaction) Commit() FutureNil

Commit attempts to commit the modifications made in the transaction to the database. Waiting on the returned future will block the calling goroutine until the transaction has either been committed successfully or an error is encountered. Any error should be passed to (Transaction).OnError to determine if the error is retryable or not.

As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. For more information, see https://apple.github.io/foundationdb/developer-guide.html#transactions-with-unknown-results.

func (Transaction) CompareAndClear 

func (t Transaction) CompareAndClear(key KeyConvertible, param []byte)

Performs an atomic “compare and clear“ operation. If the existing value in the database is equal to the given value, then given key is cleared.

func (Transaction) Get 

func (t Transaction) Get(key KeyConvertible) FutureByteSlice

Get returns the (future) value associated with the specified key. The read is performed asynchronously and does not block the calling goroutine. The future will become ready when the read is complete.

func (Transaction) GetApproximateSize 

func (t Transaction) GetApproximateSize() FutureInt64

Returns a future that is the approximate transaction size so far in this transaction, which is the summation of the estimated size of mutations, read conflict ranges, and write conflict ranges.

func (Transaction) GetCommittedVersion 

func (t Transaction) GetCommittedVersion() (int64, error)

(Infrequently used) GetCommittedVersion returns the version number at which a successful commit modified the database. This must be called only after the successful (non-error) completion of a call to Commit on this Transaction, or the behavior is undefined. Read-only transactions do not modify the database when committed and will have a committed version of -1. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.

func (Transaction) GetDatabase 

func (t Transaction) GetDatabase() Database

GetDatabase returns a handle to the database with which this transaction is interacting.

func (Transaction) GetEstimatedRangeSizeBytes 

func (t Transaction) GetEstimatedRangeSizeBytes(r ExactRange) FutureInt64

GetEstimatedRangeSizeBytes returns an estimate for the number of bytes stored in the given range. Note: the estimated size is calculated based on the sampling done by FDB server. The sampling algorithm works roughly in this way: the larger the key-value pair is, the more likely it would be sampled and the more accurate its sampled size would be. And due to that reason it is recommended to use this API to query against large ranges for accuracy considerations. For a rough reference, if the returned size is larger than 3MB, one can consider the size to be accurate.

func (Transaction) GetKey 

func (t Transaction) GetKey(sel Selectable) FutureKey

GetKey returns the future key referenced by the provided key selector. The read is performed asynchronously and does not block the calling goroutine. The future will become ready when the read version is available.

By default, the key is cached for the duration of the transaction, providing a potential performance benefit. However, the value of the key is also retrieved, using network bandwidth. Invoking (TransactionOptions).SetReadYourWritesDisable will avoid both the caching and the increased network bandwidth.

func (Transaction) GetRange 

func (t Transaction) GetRange(r Range, options RangeOptions) RangeResult

GetRange performs a range read. The returned RangeResult represents all KeyValue objects kv where beginKey <= kv.Key < endKey, ordered by kv.Key (where beginKey and endKey are the keys described by the key selectors returned by r.FDBKeySelectors). All reads performed as a result of GetRange are asynchronous and do not block the calling goroutine.

func (Transaction) GetRangeSplitPoints 

func (t Transaction) GetRangeSplitPoints(r ExactRange, chunkSize int64) FutureKeyArray

GetRangeSplitPoints returns a list of keys that can split the given range into (roughly) equally sized chunks based on chunkSize. Note: the returned split points contain the start key and end key of the given range.

func (Transaction) GetReadVersion 

func (t Transaction) GetReadVersion() FutureInt64

(Infrequently used) GetReadVersion returns the (future) transaction read version. The read is performed asynchronously and does not block the calling goroutine. The future will become ready when the read version is available.

func (Transaction) GetVersionstamp 

func (t Transaction) GetVersionstamp() FutureKey

(Infrequently used) Returns a future which will contain the versionstamp which was used by any versionstamp operations in this transaction. The future will be ready only after the successful completion of a call to Commit on this Transaction. Read-only transactions do not modify the database when committed and will result in the future completing with an error. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.

func (Transaction) LocalityGetAddressesForKey 

func (t Transaction) LocalityGetAddressesForKey(key KeyConvertible) FutureStringSlice

LocalityGetAddressesForKey returns the (future) public network addresses of each of the storage servers responsible for storing key and its associated value. The read is performed asynchronously and does not block the calling goroutine. The future will become ready when the read is complete.

func (Transaction) Max 

func (t Transaction) Max(key KeyConvertible, param []byte)

Performs a little-endian comparison of byte strings. If the existing value in the database is not present or shorter than “param“, it is first extended to the length of “param“ with zero bytes. If “param“ is shorter than the existing value in the database, the existing value is truncated to match the length of “param“. The larger of the two values is then stored in the database.

func (Transaction) Min 

func (t Transaction) Min(key KeyConvertible, param []byte)

Performs a little-endian comparison of byte strings. If the existing value in the database is not present, then “param“ is stored in the database. If the existing value in the database is shorter than “param“, it is first extended to the length of “param“ with zero bytes. If “param“ is shorter than the existing value in the database, the existing value is truncated to match the length of “param“. The smaller of the two values is then stored in the database.

func (Transaction) OnError 

func (t Transaction) OnError(e Error) FutureNil

OnError determines whether an error returned by a Transaction method is retryable. Waiting on the returned future will return the same error when fatal, or return nil (after blocking the calling goroutine for a suitable delay) for retryable errors.

Typical code will not use OnError directly. (Database).Transact uses OnError internally to implement a correct retry loop.

func (Transaction) Options 

func (t Transaction) Options() TransactionOptions

Options returns a TransactionOptions instance suitable for setting options specific to this transaction.

func (Transaction) Or 

func (t Transaction) Or(key KeyConvertible, param []byte)

Deprecated

func (Transaction) ReadTransact 

func (t Transaction) ReadTransact(f func(ReadTransaction) (interface{}, error)) (r interface{}, e error)

ReadTransact executes the caller-provided function, passing it the Transaction receiver object (as a ReadTransaction).

A panic of type Error during execution of the function will be recovered and returned to the caller as an error, but ReadTransact will not retry the function.

By satisfying the ReadTransactor interface, Transaction may be passed to a read-only transactional function from another (possibly read-only) transactional function, allowing composition.

See the ReadTransactor interface for an example of using ReadTransact with Transaction, Snapshot and Database objects.

func (Transaction) Reset 

func (t Transaction) Reset()

Reset rolls back a transaction, completely resetting it to its initial state. This is logically equivalent to destroying the transaction and creating a new one.

func (Transaction) Set 

func (t Transaction) Set(key KeyConvertible, value []byte)

Set associated the given key and value, overwriting any previous association with key. Set returns immediately, having modified the snapshot of the database represented by the transaction.

func (Transaction) SetReadVersion 

func (t Transaction) SetReadVersion(version int64)

(Infrequently used) SetReadVersion sets the database version that the transaction will read from the database. The database cannot guarantee causal consistency if this method is used (the transactions reads will be causally consistent only if the provided read version has that property).

func (Transaction) SetVersionstampedKey 

func (t Transaction) SetVersionstampedKey(key KeyConvertible, param []byte)

Transforms “key“ using a versionstamp for the transaction. Sets the transformed key in the database to “param“. The key is transformed by removing the final four bytes from the key and reading those as a little-Endian 32-bit integer to get a position “pos“. The 10 bytes of the key from “pos“ to “pos + 10“ are replaced with the versionstamp of the transaction used. The first byte of the key is position 0. A versionstamp is a 10 byte, unique, monotonically (but not sequentially) increasing value for each committed transaction. The first 8 bytes are the committed version of the database (serialized in big-Endian order). The last 2 bytes are monotonic in the serialization order for transactions. WARNING: At this time, versionstamps are compatible with the Tuple layer only in the Java, Python, and Go bindings. Also, note that prior to API version 520, the offset was computed from only the final two bytes rather than the final four bytes.

func (Transaction) SetVersionstampedValue 

func (t Transaction) SetVersionstampedValue(key KeyConvertible, param []byte)

Transforms “param“ using a versionstamp for the transaction. Sets the “key“ given to the transformed “param“. The parameter is transformed by removing the final four bytes from “param“ and reading those as a little-Endian 32-bit integer to get a position “pos“. The 10 bytes of the parameter from “pos“ to “pos + 10“ are replaced with the versionstamp of the transaction used. The first byte of the parameter is position 0. A versionstamp is a 10 byte, unique, monotonically (but not sequentially) increasing value for each committed transaction. The first 8 bytes are the committed version of the database (serialized in big-Endian order). The last 2 bytes are monotonic in the serialization order for transactions. WARNING: At this time, versionstamps are compatible with the Tuple layer only in the Java, Python, and Go bindings. Also, note that prior to API version 520, the versionstamp was always placed at the beginning of the parameter rather than computing an offset.

func (Transaction) Snapshot 

func (t Transaction) Snapshot() Snapshot

Snapshot returns a Snapshot object, suitable for performing snapshot reads. Snapshot reads offer a more relaxed isolation level than FoundationDB's default serializable isolation, reducing transaction conflicts but making it harder to reason about concurrency.

For more information on snapshot reads, see https://apple.github.io/foundationdb/developer-guide.html#snapshot-reads.

func (Transaction) Transact 

func (t Transaction) Transact(f func(Transaction) (interface{}, error)) (r interface{}, e error)

Transact executes the caller-provided function, passing it the Transaction receiver object.

A panic of type Error during execution of the function will be recovered and returned to the caller as an error, but Transact will not retry the function or commit the Transaction after the caller-provided function completes.

By satisfying the Transactor interface, Transaction may be passed to a transactional function from another transactional function, allowing composition. The outermost transactional function must have been provided a Database, or else the transaction will never be committed.

See the Transactor interface for an example of using Transact with Transaction and Database objects.

func (Transaction) Watch 

func (t Transaction) Watch(key KeyConvertible) FutureNil

Watch creates a watch and returns a FutureNil that will become ready when the watch reports a change to the value of the specified key.

A watchs behavior is relative to the transaction that created it. A watch will report a change in relation to the keys value as readable by that transaction. The initial value used for comparison is either that of the transactions read version or the value as modified by the transaction itself prior to the creation of the watch. If the value changes and then changes back to its initial value, the watch might not report the change.

Until the transaction that created it has been committed, a watch will not report changes made by other transactions. In contrast, a watch will immediately report changes made by the transaction itself. Watches cannot be created if the transaction has called SetReadYourWritesDisable on the Transaction options, and an attempt to do so will return a watches_disabled error.

If the transaction used to create a watch encounters an error during commit, then the watch will be set with that error. A transaction whose commit result is unknown will set all of its watches with the commit_unknown_result error. If an uncommitted transaction is reset or destroyed, then any watches it created will be set with the transaction_cancelled error.

By default, each database connection can have no more than 10,000 watches that have not yet reported a change. When this number is exceeded, an attempt to create a watch will return a too_many_watches error. This limit can be changed using SetMaxWatches on the Database. Because a watch outlives the transaction that creates it, any watch that is no longer needed should be cancelled by calling (FutureNil).Cancel on its returned future.

func (Transaction) Xor 

func (t Transaction) Xor(key KeyConvertible, param []byte)

Deprecated

type TransactionOptions 

type TransactionOptions struct {
	// contains filtered or unexported fields
}

TransactionOptions is a handle with which to set options that affect a Transaction object. A TransactionOptions instance should be obtained with the (Transaction).Options method.

func (TransactionOptions) SetAccessSystemKeys 

func (o TransactionOptions) SetAccessSystemKeys() error

Allows this transaction to read and modify system keys (those that start with the byte 0xFF). Implies raw_access.

func (TransactionOptions) SetAuthorizationToken 

func (o TransactionOptions) SetAuthorizationToken(param string) error

Attach given authorization token to the transaction such that subsequent tenant-aware requests are authorized

Parameter: A JSON Web Token authorized to access data belonging to one or more tenants, indicated by 'tenants' claim of the token's payload.

func (TransactionOptions) SetAutoThrottleTag 

func (o TransactionOptions) SetAutoThrottleTag(param string) error

Adds a tag to the transaction that can be used to apply manual or automatic targeted throttling. At most 5 tags can be set on a transaction.

Parameter: String identifier used to associated this transaction with a throttling group. Must not exceed 16 characters.

func (TransactionOptions) SetAutomaticIdempotency 

func (o TransactionOptions) SetAutomaticIdempotency() error

Automatically assign a random 16 byte idempotency id for this transaction. Prevents commits from failing with “commit_unknown_result“. WARNING: If you are also using the multiversion client or transaction timeouts, if either cluster_version_changed or transaction_timed_out was thrown during a commit, then that commit may have already succeeded or may succeed in the future. This feature is in development and not ready for general use.

func (TransactionOptions) SetBypassStorageQuota 

func (o TransactionOptions) SetBypassStorageQuota() error

Allows this transaction to bypass storage quota enforcement. Should only be used for transactions that directly or indirectly decrease the size of the tenant group's data.

func (TransactionOptions) SetBypassUnreadable 

func (o TransactionOptions) SetBypassUnreadable() error

Allows “get“ operations to read from sections of keyspace that have become unreadable because of versionstamp operations. These reads will view versionstamp operations as if they were set operations that did not fill in the versionstamp.

func (TransactionOptions) SetCausalReadDisable 

func (o TransactionOptions) SetCausalReadDisable() error

Not yet implemented.

func (TransactionOptions) SetCausalReadRisky 

func (o TransactionOptions) SetCausalReadRisky() error

The read version will be committed, and usually will be the latest committed, but might not be the latest committed in the event of a simultaneous fault and misbehaving clock.

func (TransactionOptions) SetCausalWriteRisky 

func (o TransactionOptions) SetCausalWriteRisky() error

The transaction, if not self-conflicting, may be committed a second time after commit succeeds, in the event of a fault

func (TransactionOptions) SetConsistencyCheckRequiredReplicas 

func (o TransactionOptions) SetConsistencyCheckRequiredReplicas(param int64) error

Specifies the number of storage server replica results that the load balancer needs to compare when enable_replica_consistency_check option is set.

Parameter: Number of storage replicas over which the load balancer consistency check is done.

func (TransactionOptions) SetDebugRetryLogging 

func (o TransactionOptions) SetDebugRetryLogging(param string) error

Not yet implemented.

func (TransactionOptions) SetDebugTransactionIdentifier 

func (o TransactionOptions) SetDebugTransactionIdentifier(param string) error

Sets a client provided identifier for the transaction that will be used in scenarios like tracing or profiling. Client trace logging or transaction profiling must be separately enabled.

Parameter: String identifier to be used when tracing or profiling this transaction. The identifier must not exceed 100 characters.

func (TransactionOptions) SetDurabilityDatacenter 

func (o TransactionOptions) SetDurabilityDatacenter() error

Not yet implemented.

func (TransactionOptions) SetDurabilityDevNullIsWebScale 

func (o TransactionOptions) SetDurabilityDevNullIsWebScale() error

Deprecated

func (TransactionOptions) SetDurabilityRisky 

func (o TransactionOptions) SetDurabilityRisky() error

Not yet implemented.

func (TransactionOptions) SetEnableReplicaConsistencyCheck 

func (o TransactionOptions) SetEnableReplicaConsistencyCheck() error

Enables replica consistency check, which compares the results returned by storage server replicas (as many as specified by consistency_check_required_replicas option) for a given read request, in client-side load balancer.

func (TransactionOptions) SetExpensiveClearCostEstimationEnable 

func (o TransactionOptions) SetExpensiveClearCostEstimationEnable() error

Asks storage servers for how many bytes a clear key range contains. Otherwise uses the location cache to roughly estimate this.

func (TransactionOptions) SetIncludePortInAddress 

func (o TransactionOptions) SetIncludePortInAddress() error

Addresses returned by get_addresses_for_key include the port when enabled. As of api version 630, this option is enabled by default and setting this has no effect.

func (TransactionOptions) SetInitializeNewDatabase 

func (o TransactionOptions) SetInitializeNewDatabase() error

This is a write-only transaction which sets the initial configuration. This option is designed for use by database system tools only.

func (TransactionOptions) SetLockAware 

func (o TransactionOptions) SetLockAware() error

The transaction can read and write to locked databases, and is responsible for checking that it took the lock.

func (TransactionOptions) SetLogTransaction 

func (o TransactionOptions) SetLogTransaction() error

Enables tracing for this transaction and logs results to the client trace logs. The DEBUG_TRANSACTION_IDENTIFIER option must be set before using this option, and client trace logging must be enabled to get log output.

func (TransactionOptions) SetMaxRetryDelay 

func (o TransactionOptions) SetMaxRetryDelay(param int64) error

Set the maximum amount of backoff delay incurred in the call to “onError“ if the error is retryable. Defaults to 1000 ms. Valid parameter values are “[0, INT_MAX]“. If the maximum retry delay is less than the current retry delay of the transaction, then the current retry delay will be clamped to the maximum retry delay. Prior to API version 610, like all other transaction options, the maximum retry delay must be reset after a call to “onError“. If the API version is 610 or greater, the retry limit is not reset after an “onError“ call. Note that at all API versions, it is safe and legal to set the maximum retry delay each time the transaction begins, so most code written assuming the older behavior can be upgraded to the newer behavior without requiring any modification, and the caller is not required to implement special logic in retry loops to only conditionally set this option.

Parameter: value in milliseconds of maximum delay

func (TransactionOptions) SetNextWriteNoWriteConflictRange 

func (o TransactionOptions) SetNextWriteNoWriteConflictRange() error

The next write performed on this transaction will not generate a write conflict range. As a result, other transactions which read the key(s) being modified by the next write will not conflict with this transaction. Care needs to be taken when using this option on a transaction that is shared between multiple threads. When setting this option, write conflict ranges will be disabled on the next write operation, regardless of what thread it is on.

func (TransactionOptions) SetPriorityBatch 

func (o TransactionOptions) SetPriorityBatch() error

Specifies that this transaction should be treated as low priority and that default priority transactions will be processed first. Batch priority transactions will also be throttled at load levels smaller than for other types of transactions and may be fully cut off in the event of machine failures. Useful for doing batch work simultaneously with latency-sensitive work

func (TransactionOptions) SetPrioritySystemImmediate 

func (o TransactionOptions) SetPrioritySystemImmediate() error

Specifies that this transaction should be treated as highest priority and that lower priority transactions should block behind this one. Use is discouraged outside of low-level tools

func (TransactionOptions) SetRawAccess 

func (o TransactionOptions) SetRawAccess() error

Allows this transaction to access the raw key-space when tenant mode is on.

func (TransactionOptions) SetReadAheadDisable 

func (o TransactionOptions) SetReadAheadDisable() error

Deprecated

func (TransactionOptions) SetReadLockAware 

func (o TransactionOptions) SetReadLockAware() error

The transaction can read from locked databases.

func (TransactionOptions) SetReadPriorityHigh 

func (o TransactionOptions) SetReadPriorityHigh() error

Use high read priority for subsequent read requests in this transaction.

func (TransactionOptions) SetReadPriorityLow 

func (o TransactionOptions) SetReadPriorityLow() error

Use low read priority for subsequent read requests in this transaction.

func (TransactionOptions) SetReadPriorityNormal 

func (o TransactionOptions) SetReadPriorityNormal() error

Use normal read priority for subsequent read requests in this transaction. This is the default read priority.

func (TransactionOptions) SetReadServerSideCacheDisable 

func (o TransactionOptions) SetReadServerSideCacheDisable() error

Storage server should not cache disk blocks needed for subsequent read requests in this transaction. This can be used to avoid cache pollution for reads not expected to be repeated.

func (TransactionOptions) SetReadServerSideCacheEnable 

func (o TransactionOptions) SetReadServerSideCacheEnable() error

Storage server should cache disk blocks needed for subsequent read requests in this transaction. This is the default behavior.

func (TransactionOptions) SetReadSystemKeys 

func (o TransactionOptions) SetReadSystemKeys() error

Allows this transaction to read system keys (those that start with the byte 0xFF). Implies raw_access.

func (TransactionOptions) SetReadYourWritesDisable 

func (o TransactionOptions) SetReadYourWritesDisable() error

Reads performed by a transaction will not see any prior mutations that occurred in that transaction, instead seeing the value which was in the database at the transaction's read version. This option may provide a small performance benefit for the client, but also disables a number of client-side optimizations which are beneficial for transactions which tend to read and write the same keys within a single transaction. It is an error to set this option after performing any reads or writes on the transaction.

func (TransactionOptions) SetReportConflictingKeys 

func (o TransactionOptions) SetReportConflictingKeys() error

The transaction can retrieve keys that are conflicting with other transactions.

func (TransactionOptions) SetRetryLimit 

func (o TransactionOptions) SetRetryLimit(param int64) error

Set a maximum number of retries after which additional calls to “onError“ will throw the most recently seen error code. Valid parameter values are “[-1, INT_MAX]“. If set to -1, will disable the retry limit. Prior to API version 610, like all other transaction options, the retry limit must be reset after a call to “onError“. If the API version is 610 or greater, the retry limit is not reset after an “onError“ call. Note that at all API versions, it is safe and legal to set the retry limit each time the transaction begins, so most code written assuming the older behavior can be upgraded to the newer behavior without requiring any modification, and the caller is not required to implement special logic in retry loops to only conditionally set this option.

Parameter: number of times to retry

func (TransactionOptions) SetServerRequestTracing 

func (o TransactionOptions) SetServerRequestTracing() error

Sets an identifier for server tracing of this transaction. When committed, this identifier triggers logging when each part of the transaction authority encounters it, which is helpful in diagnosing slowness in misbehaving clusters. The identifier is randomly generated. When there is also a debug_transaction_identifier, both IDs are logged together.

func (TransactionOptions) SetSizeLimit 

func (o TransactionOptions) SetSizeLimit(param int64) error

Set the transaction size limit in bytes. The size is calculated by combining the sizes of all keys and values written or mutated, all key ranges cleared, and all read and write conflict ranges. (In other words, it includes the total size of all data included in the request to the cluster to commit the transaction.) Large transactions can cause performance problems on FoundationDB clusters, so setting this limit to a smaller value than the default can help prevent the client from accidentally degrading the cluster's performance. This value must be at least 32 and cannot be set to higher than 10,000,000, the default transaction size limit.

Parameter: value in bytes

func (TransactionOptions) SetSnapshotRywDisable 

func (o TransactionOptions) SetSnapshotRywDisable() error

Snapshot read operations will not see the results of writes done in the same transaction. This was the default behavior prior to API version 300.

func (TransactionOptions) SetSnapshotRywEnable 

func (o TransactionOptions) SetSnapshotRywEnable() error

Snapshot read operations will see the results of writes done in the same transaction. This is the default behavior.

func (TransactionOptions) SetSpanParent 

func (o TransactionOptions) SetSpanParent(param []byte) error

Adds a parent to the Span of this transaction. Used for transaction tracing. A span can be identified with a 33 bytes serialized binary format which consists of: 8 bytes protocol version, e.g. “0x0FDB00B073000000LL“ in little-endian format, 16 bytes trace id, 8 bytes span id, 1 byte set to 1 if sampling is enabled

Parameter: A serialized binary byte string of length 33 used to associate the span of this transaction with a parent

func (TransactionOptions) SetSpecialKeySpaceEnableWrites 

func (o TransactionOptions) SetSpecialKeySpaceEnableWrites() error

By default, users are not allowed to write to special keys. Enable this option will implicitly enable all options required to achieve the configuration change.

func (TransactionOptions) SetSpecialKeySpaceRelaxed 

func (o TransactionOptions) SetSpecialKeySpaceRelaxed() error

By default, the special key space will only allow users to read from exactly one module (a subspace in the special key space). Use this option to allow reading from zero or more modules. Users who set this option should be prepared for new modules, which may have different behaviors than the modules they're currently reading. For example, a new module might block or return an error.

func (TransactionOptions) SetTag 

func (o TransactionOptions) SetTag(param string) error

Adds a tag to the transaction that can be used to apply manual targeted throttling. At most 5 tags can be set on a transaction.

Parameter: String identifier used to associated this transaction with a throttling group. Must not exceed 16 characters.

func (TransactionOptions) SetTimeout 

func (o TransactionOptions) SetTimeout(param int64) error

Set a timeout in milliseconds which, when elapsed, will cause the transaction automatically to be cancelled. Valid parameter values are “[0, INT_MAX]“. If set to 0, will disable all timeouts. All pending and any future uses of the transaction will throw an exception. The transaction can be used again after it is reset. Prior to API version 610, like all other transaction options, the timeout must be reset after a call to “onError“. If the API version is 610 or greater, the timeout is not reset after an “onError“ call. This allows the user to specify a longer timeout on specific transactions than the default timeout specified through the “transaction_timeout“ database option without the shorter database timeout cancelling transactions that encounter a retryable error. Note that at all API versions, it is safe and legal to set the timeout each time the transaction begins, so most code written assuming the older behavior can be upgraded to the newer behavior without requiring any modification, and the caller is not required to implement special logic in retry loops to only conditionally set this option.

Parameter: value in milliseconds of timeout

func (TransactionOptions) SetTransactionLoggingEnable 

func (o TransactionOptions) SetTransactionLoggingEnable(param string) error

Deprecated

Parameter: String identifier to be used in the logs when tracing this transaction. The identifier must not exceed 100 characters.

func (TransactionOptions) SetTransactionLoggingMaxFieldLength 

func (o TransactionOptions) SetTransactionLoggingMaxFieldLength(param int64) error

Sets the maximum escaped length of key and value fields to be logged to the trace file via the LOG_TRANSACTION option, after which the field will be truncated. A negative value disables truncation.

Parameter: Maximum length of escaped key and value fields.

func (TransactionOptions) SetUseGrvCache 

func (o TransactionOptions) SetUseGrvCache() error

Allows this transaction to use cached GRV from the database context. Defaults to off. Upon first usage, starts a background updater to periodically update the cache to avoid stale read versions. The disable_client_bypass option must also be set.

func (TransactionOptions) SetUseProvisionalProxies 

func (o TransactionOptions) SetUseProvisionalProxies() error

This option should only be used by tools which change the database configuration.

func (TransactionOptions) SetUsedDuringCommitProtectionDisable 

func (o TransactionOptions) SetUsedDuringCommitProtectionDisable() error

By default, operations that are performed on a transaction while it is being committed will not only fail themselves, but they will attempt to fail other in-flight operations (such as the commit) as well. This behavior is intended to help developers discover situations where operations could be unintentionally executed after the transaction has been reset. Setting this option removes that protection, causing only the offending operation to fail.

type Transactor 

type Transactor interface {
	// Transact executes the caller-provided function, providing it with a
	// Transaction (itself a Transactor, allowing composition of transactional
	// functions).
	Transact(func(Transaction) (interface{}, error)) (interface{}, error)

	// All Transactors are also ReadTransactors, allowing them to be used with
	// read-only transactional functions.
	ReadTransactor
}

A Transactor can execute a function that requires a Transaction. Functions written to accept a Transactor are called transactional functions, and may be called with either a Database or a Transaction.

Example 
package main

import (
	"fmt"

	"github.com/apple/foundationdb/bindings/go/src/fdb"
)

const API_VERSION int = 740

func main() {
	fdb.MustAPIVersion(API_VERSION)
	db := fdb.MustOpenDefault()

	setOne := func(t fdb.Transactor, key fdb.Key, value []byte) error {
		fmt.Printf("setOne called with:  %T\n", t)
		_, e := t.Transact(func(tr fdb.Transaction) (interface{}, error) {
			// We don't actually call tr.Set here to avoid mutating a real database.
			// tr.Set(key, value)
			return nil, nil
		})
		return e
	}

	setMany := func(t fdb.Transactor, value []byte, keys ...fdb.Key) error {
		fmt.Printf("setMany called with: %T\n", t)
		_, e := t.Transact(func(tr fdb.Transaction) (interface{}, error) {
			for _, key := range keys {
				setOne(tr, key, value)
			}
			return nil, nil
		})
		return e
	}

	var e error

	fmt.Println("Calling setOne with a database:")
	e = setOne(db, []byte("foo"), []byte("bar"))
	if e != nil {
		fmt.Println(e)
		return
	}
	fmt.Println("\nCalling setMany with a database:")
	e = setMany(db, []byte("bar"), fdb.Key("foo1"), fdb.Key("foo2"), fdb.Key("foo3"))
	if e != nil {
		fmt.Println(e)
		return
	}

}

Output:

Calling setOne with a database:
setOne called with:  fdb.Database

Calling setMany with a database:
setMany called with: fdb.Database
setOne called with:  fdb.Transaction
setOne called with:  fdb.Transaction
setOne called with:  fdb.Transaction

Source Files

View all Source files

Directories

Path Synopsis
Package directory provides a tool for managing related subspaces.
 Package directory provides a tool for managing related subspaces.
Package subspace provides a convenient way to use FoundationDB tuples to define namespaces for different categories of data.
 Package subspace provides a convenient way to use FoundationDB tuples to define namespaces for different categories of data.
Package tuple provides a layer for encoding and decoding multi-element tuples into keys usable by FoundationDB.
 Package tuple provides a layer for encoding and decoding multi-element tuples into keys usable by FoundationDB.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.