foundationdb: github.com/apple/foundationdb/bindings/go/src/fdb Index | Examples | Files | Directories

package fdb

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

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://www.foundationdb.org/download/.

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(610)

    // 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
})

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, Max, Min, SetVersionstampedKey, SetVersionstampedValue (all methods on Transaction).

Index

Examples

Package Files

cluster.go database.go doc.go errors.go fdb.go futures.go generated.go keyselector.go range.go snapshot.go transaction.go

Constants

const DefaultClusterFile string = ""

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

func APIVersion Uses

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.

Currently, this package supports API versions 200 through 610.

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 Uses

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 Uses

func IsAPIVersionSelected() bool

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

func MustAPIVersion Uses

func MustAPIVersion(version int)

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

func MustGetAPIVersion Uses

func MustGetAPIVersion() int

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

func StartNetwork Uses

func StartNetwork() error

StartNetwork initializes the FoundationDB client networking engine. It is not necessary to call StartNetwork when using the fdb.Open or fdb.OpenDefault functions to obtain a database handle. StartNetwork must not be called more than once.

func Strinc Uses

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.

type Cluster Uses

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

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.

It is generally preferable to use Open or OpenDefault to obtain a database handle directly.

func CreateCluster Uses

func CreateCluster(clusterFile string) (Cluster, error)

CreateCluster returns a cluster handle to the FoundationDB cluster identified by the provided cluster file.

func (Cluster) OpenDatabase Uses

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

OpenDatabase returns a database handle from the FoundationDB cluster. It is generally preferable to use Open or OpenDefault to obtain a database handle directly.

In the current release, the database name must be []byte("DB").

type Database Uses

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 Uses

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

MustOpen is like Open but panics if the database cannot be opened.

func MustOpenDefault Uses

func MustOpenDefault() Database

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

func Open Uses

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

Open returns a database handle to the named database from the FoundationDB cluster identified by the provided cluster file and database name. The FoundationDB client networking engine will be initialized first, if necessary.

In the current release, the database name must be []byte("DB").

func OpenDefault Uses

func OpenDefault() (Database, error)

OpenDefault returns a database handle to the default database from the FoundationDB cluster identified by the DefaultClusterFile on the current machine. The FoundationDB client networking engine will be initialized first, if necessary.

Code:

var e error

e = fdb.APIVersion(400)
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 and the database name []byte("DB").
db, e := fdb.OpenDefault()
if e != nil {
    fmt.Printf("Unable to open default database: %v\n", e)
    return
}

_ = db

func (Database) CreateTransaction Uses

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 Uses

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 Uses

func (d Database) Options() DatabaseOptions

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

func (Database) ReadTransact Uses

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.

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) Transact Uses

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.

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 DatabaseId Uses

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

type DatabaseOptions Uses

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 Uses

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: Hexadecimal ID

func (DatabaseOptions) SetLocationCacheSize Uses

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 Uses

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 Uses

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

type Error Uses

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 Uses

func (e Error) Error() string

type ErrorPredicate Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 FutureNil Uses

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 Uses

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 Uses

type Key []byte

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

func (Key) FDBKey Uses

func (k Key) FDBKey() Key

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

type KeyConvertible Uses

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 Uses

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 Uses

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.

Code:

fdb.MustAPIVersion(400)
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 Uses

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

FDBRangeKeySelectors allows KeyRange to satisfy the Range interface.

func (KeyRange) FDBRangeKeys Uses

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

FDBRangeKeys allows KeyRange to satisfy the ExactRange interface.

type KeySelector Uses

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 Uses

func FirstGreaterOrEqual(key KeyConvertible) KeySelector

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

func FirstGreaterThan Uses

func FirstGreaterThan(key KeyConvertible) KeySelector

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

func LastLessOrEqual Uses

func LastLessOrEqual(key KeyConvertible) KeySelector

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

func LastLessThan Uses

func LastLessThan(key KeyConvertible) KeySelector

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

func (KeySelector) FDBKeySelector Uses

func (ks KeySelector) FDBKeySelector() KeySelector

type KeyValue Uses

type KeyValue struct {
    Key   Key
    Value []byte
}

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

type NetworkOptions Uses

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 Uses

func Options() NetworkOptions

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

func (NetworkOptions) SetBuggifyDisable Uses

func (o NetworkOptions) SetBuggifyDisable() error

Not yet implemented.

func (NetworkOptions) SetBuggifyEnable Uses

func (o NetworkOptions) SetBuggifyEnable() error

Not yet implemented.

func (NetworkOptions) SetBuggifySectionActivatedProbability Uses

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 Uses

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 Uses

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) SetClusterFile Uses

func (o NetworkOptions) SetClusterFile(param string) error

Deprecated

Parameter: path to cluster file

func (NetworkOptions) SetDisableClientStatisticsLogging Uses

func (o NetworkOptions) SetDisableClientStatisticsLogging() error

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

func (NetworkOptions) SetDisableLocalClient Uses

func (o NetworkOptions) SetDisableLocalClient() error

Prevents connections through the local client, allowing only connections through externally loaded client libraries. Intended primarily for testing.

func (NetworkOptions) SetDisableMultiVersionClientApi Uses

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) SetEnableSlowTaskProfiling Uses

func (o NetworkOptions) SetEnableSlowTaskProfiling() error

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

func (NetworkOptions) SetExternalClientDirectory Uses

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 Uses

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) SetKnob Uses

func (o NetworkOptions) SetKnob(param string) error

Set internal tuning or debugging knobs

Parameter: knob_name=knob_value

func (NetworkOptions) SetLocalAddress Uses

func (o NetworkOptions) SetLocalAddress(param string) error

Deprecated

Parameter: IP:PORT

func (NetworkOptions) SetTLSCaBytes Uses

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

Set the ca bundle

Parameter: ca bundle

func (NetworkOptions) SetTLSCaPath Uses

func (o NetworkOptions) SetTLSCaPath(param string) error

Set the file from which to load the certificate authority bundle

Parameter: file path

func (NetworkOptions) SetTLSCertBytes Uses

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

Set the certificate chain

Parameter: certificates

func (NetworkOptions) SetTLSCertPath Uses

func (o NetworkOptions) SetTLSCertPath(param string) error

Set the file from which to load the certificate chain

Parameter: file path

func (NetworkOptions) SetTLSKeyBytes Uses

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

Set the private key corresponding to your own certificate

Parameter: key

func (NetworkOptions) SetTLSKeyPath Uses

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 Uses

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 Uses

func (o NetworkOptions) SetTLSPlugin(param string) error

Deprecated

Parameter: file path or linker-resolved name

func (NetworkOptions) SetTLSVerifyPeers Uses

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

Set the peer certificate field verification criteria

Parameter: verification pattern

func (NetworkOptions) SetTraceEnable Uses

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) SetTraceLogGroup Uses

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 Uses

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) SetTraceRollSize Uses

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

type Range Uses

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 Uses

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.

Code:

fdb.MustAPIVersion(400)
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 Uses

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 Uses

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 Uses

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 Uses

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.
    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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

type ReadTransaction interface {
    Get(key KeyConvertible) FutureByteSlice
    GetKey(sel Selectable) FutureKey
    GetRange(r Range, options RangeOptions) RangeResult
    GetReadVersion() FutureInt64
    GetDatabase() Database
    Snapshot() Snapshot

    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 Uses

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.

Code:

fdb.MustAPIVersion(400)
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 Uses

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 Uses

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 Uses

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

FDBRangeKeySelectors allows SelectorRange to satisfy the Range interface.

type Snapshot Uses

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) Get Uses

func (s Snapshot) Get(key KeyConvertible) FutureByteSlice

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

func (Snapshot) GetDatabase Uses

func (s Snapshot) GetDatabase() Database

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

func (Snapshot) GetKey Uses

func (s Snapshot) GetKey(sel Selectable) FutureKey

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

func (Snapshot) GetRange Uses

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

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

func (Snapshot) GetReadVersion Uses

func (s Snapshot) GetReadVersion() FutureInt64

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

func (Snapshot) ReadTransact Uses

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 Uses

func (s Snapshot) Snapshot() Snapshot

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

type StreamingMode Uses

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.
    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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Deprecated

func (Transaction) AppendIfFits Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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.

func (Transaction) Commit Uses

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) Get Uses

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) GetCommittedVersion Uses

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 Uses

func (t Transaction) GetDatabase() Database

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

func (Transaction) GetKey Uses

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 Uses

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) GetReadVersion Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (t Transaction) Options() TransactionOptions

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

func (Transaction) Or Uses

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

Deprecated

func (Transaction) ReadTransact Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 and Python 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 Uses

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 and Python 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 Uses

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 Uses

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 Uses

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 Uses

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

Deprecated

type TransactionOptions Uses

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 Uses

func (o TransactionOptions) SetAccessSystemKeys() error

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

func (TransactionOptions) SetCausalReadDisable Uses

func (o TransactionOptions) SetCausalReadDisable() error

Not yet implemented.

func (TransactionOptions) SetCausalReadRisky Uses

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 fault or partition

func (TransactionOptions) SetCausalWriteRisky Uses

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) SetDebugRetryLogging Uses

func (o TransactionOptions) SetDebugRetryLogging(param string) error

Not yet implemented.

func (TransactionOptions) SetDurabilityDatacenter Uses

func (o TransactionOptions) SetDurabilityDatacenter() error

Not yet implemented.

func (TransactionOptions) SetDurabilityDevNullIsWebScale Uses

func (o TransactionOptions) SetDurabilityDevNullIsWebScale() error

Deprecated

func (TransactionOptions) SetDurabilityRisky Uses

func (o TransactionOptions) SetDurabilityRisky() error

Not yet implemented.

func (TransactionOptions) SetInitializeNewDatabase Uses

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 Uses

func (o TransactionOptions) SetLockAware() error

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

func (TransactionOptions) SetMaxRetryDelay Uses

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]“. Like all transaction options, the maximum retry delay must be reset after a call to onError. 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.

Parameter: value in milliseconds of maximum delay

func (TransactionOptions) SetNextWriteNoWriteConflictRange Uses

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 Uses

func (o TransactionOptions) SetPriorityBatch() error

Specifies that this transaction should be treated as low priority and that default priority transactions should be processed first. Useful for doing batch work simultaneously with latency-sensitive work

func (TransactionOptions) SetPrioritySystemImmediate Uses

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) SetReadAheadDisable Uses

func (o TransactionOptions) SetReadAheadDisable() error

Deprecated

func (TransactionOptions) SetReadLockAware Uses

func (o TransactionOptions) SetReadLockAware() error

The transaction can read from locked databases.

func (TransactionOptions) SetReadSystemKeys Uses

func (o TransactionOptions) SetReadSystemKeys() error

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

func (TransactionOptions) SetReadYourWritesDisable Uses

func (o TransactionOptions) SetReadYourWritesDisable() error

Reads performed by a transaction will not see any prior mutations that occured 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.

func (TransactionOptions) SetRetryLimit Uses

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. Like all transaction options, the retry limit must be reset after a call to onError. This behavior allows the user to make the retry limit dynamic.

Parameter: number of times to retry

func (TransactionOptions) SetSnapshotRywDisable Uses

func (o TransactionOptions) SetSnapshotRywDisable() error

Snapshot read operations will not see the results of writes done in the same transaction.

func (TransactionOptions) SetSnapshotRywEnable Uses

func (o TransactionOptions) SetSnapshotRywEnable() error

Snapshot read operations will see the results of writes done in the same transaction.

func (TransactionOptions) SetTimeout Uses

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. Like all transaction options, a timeout must be reset after a call to onError. This behavior allows the user to make the timeout dynamic.

Parameter: value in milliseconds of timeout

func (TransactionOptions) SetTransactionLoggingEnable Uses

func (o TransactionOptions) SetTransactionLoggingEnable(param string) error

Enables tracing for this transaction and logs results to the client trace logs. Client trace logging must be enabled to get log output.

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

func (TransactionOptions) SetUsedDuringCommitProtectionDisable Uses

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 Uses

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.

Code:

fdb.MustAPIVersion(400)
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

Directories

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

Package fdb imports 8 packages (graph) and is imported by 7 packages. Updated 2018-12-05. Refresh now. Tools for package owners.