client: goshawkdb.io/client Index | Files

package client

import "goshawkdb.io/client"

Package client is the Go client for GoshawkDB. This is a fully featured client, supporting retry and nested transactions.

This client is available under the Apache License, Version 2.0. A copy of this License is included in this repository, or available from http://www.apache.org/licenses/LICENSE-2.0

Index

Package Files

cache.go connection.go doc.go transaction.go

type Capability Uses

type Capability uint8
const (
    // An ObjectRef with the None capability grants you no actions on
    // the object.
    None Capability = iota
    // An ObjectRef with the Read capability grants you the ability to
    // read the object value, its version and its references.
    Read Capability = iota
    // An ObjectRef with the Write capability grants you the ability to
    // set (write) the object value and references.
    Write Capability = iota
    // An ObjectRef with the ReadWrite capability grants you both the
    // Read and Write capabilities.
    ReadWrite Capability = iota
)

type Connection Uses

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

Connection represents a connection to the GoshawkDB server. A connection may only be used by one go-routine at a time.

func NewConnection Uses

func NewConnection(hostPort string, clientCertAndKeyPEM, clusterCertPEM []byte) (*Connection, error)

Create a new connection. The hostPort parameter can be either hostname:port or ip:port. If port is not provided the default port of 7894 is used. This will block until a connection is established and ready to use, or an error occurs. The clientCertAndKeyPEM parameter should be the client certificate followed by private key in PEM format. The clusterCert parameter is the cluster certificate. This is optional, but recommended: without it, the client will not be able to verify the server to which it connects.

func (*Connection) RunTransaction Uses

func (conn *Connection) RunTransaction(fun func(*Txn) (interface{}, error)) (interface{}, *Stats, error)

Run a transaction. The transaction is the function supplied, and the function is invoked potentially several times until it completes successfully: either committing or choosing to abort. The function should therefore be referentially transparent. Returning any non-nil error will cause the transaction to be aborted. The only exception to this rule is that returning Restart when the transaction has identified a restart is required will cause the transaction to be immediately restarted (methods on ObjectRef will return Restart as necessary).

The function's final results are returned by this method, along with statistics regarding how the transaction proceeded.

This function automatically detects and creates nested transactions: it is perfectly safe (and expected) to call RunTransaction from within a transaction.

func (*Connection) Shutdown Uses

func (conn *Connection) Shutdown()

Shutdown the connection. This will block until the connection is closed.

type ObjectRef Uses

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

ObjectRef represents a reference (or pointer) to an object in the database, combined with a capability to act on that object. ObjectRefs are linked to Connections: if you're using multiple Connections, it is not permitted to use the same ObjectRef in both connections; you can either navigate to the same object in both connections or once that is done in each connection, you can use GetObject to get a new ObjectRef to the same object in the other connection. Within the same Connection, and within nested transactions, ObjectRefs may be freely reused.

func (ObjectRef) GrantCapability Uses

func (objRef ObjectRef) GrantCapability(capability Capability) ObjectRef

Create a new ObjectRef to the same database object but with different capabilities. This will always succeed, but the transaction may be rejected if you attempt to grant capabilities you have not received. From a ReadWrite capability, you can grant anything. From a Read capability you can grant only a Read or None. From a Write capability you can grant only a Write or None. From a None capability you can only grant a None.

func (ObjectRef) Id Uses

func (objRef ObjectRef) Id() *common.VarUUId

Returns the identifier of the object to which this reference refers. From this you can convert to a byte[] which can be useful for example when using the collections library and you wish to use objects as keys.

func (ObjectRef) ObjectCapability Uses

func (objRef ObjectRef) ObjectCapability() Capability

Reveal which capabilities have been discovered by this client on the object to which this ObjectRef refers. This is the union of the capabilities from all of the ObjectRefs that refer to this same object as encountered, to date, by this connection.

func (ObjectRef) RefCapability Uses

func (objRef ObjectRef) RefCapability() Capability

Reveal which capabilities this ObjectRef contains.

func (ObjectRef) References Uses

func (o ObjectRef) References() ([]ObjectRef, error)

Returns the slice of objects to which this object refers. Returns a copy of the current references so you are safe to modify it, but you will need to call the Set method for any modifications to take effect. If the error is Restart, you should return Restart as an error in the transaction. This method will error if you do not have the Read capability for this object.

func (ObjectRef) ReferencesSameAs Uses

func (a ObjectRef) ReferencesSameAs(b ObjectRef) bool

Use this method to test if two ObjectRefs are references to the same object in the database. This method does not test for equality of capability within the ObjectRefs.

func (ObjectRef) Set Uses

func (o ObjectRef) Set(value []byte, references ...ObjectRef) error

Sets the value and references of the current object. If the value contains any references to other objects, they must be explicitly declared as references otherwise on retrieval you will not be able to navigate to those objects. Note that the order of references is stable and may contain duplicates. This method takes copies of both the value and the references so if you modify either after calling this method, your modifications will not take effect. If the error is Restart, you should return Restart as an error in the transaction. This method will error if you do not have the Write capability for this object.

func (ObjectRef) String Uses

func (objRef ObjectRef) String() string

func (ObjectRef) Value Uses

func (o ObjectRef) Value() ([]byte, error)

Returns the current value of this object. Returns a copy of the current value so you are safe to modify it but you will need to call the Set method for any modifications to take effect. If the error is Restart, you should return Restart as an error in the transaction. This method will error if you do not have the Read capability for this object.

func (ObjectRef) ValueReferences Uses

func (o ObjectRef) ValueReferences() ([]byte, []ObjectRef, error)

Returns the current value of this object and the slice of objects to which this object refers. Returns a copy of the current value and a copy of the current references so you are safe to modify them but you will need to call the Set method for any modifications to take effect. If the error is Restart, you should return Restart as an error in the transaction. This method will error if you do not have the Read capability for this object.

func (ObjectRef) Version Uses

func (o ObjectRef) Version() (*common.TxnId, error)

Returns the TxnId of the last transaction that wrote to this object. If the error is Restart, you should return Restart as an error in the transaction. This method will error if you do not have the Read capability for this object.

type Stats Uses

type Stats struct {
    // Any objects that were loaded from the RM as part of this transaction are recorded
    Loads map[common.VarUUId]time.Duration
    // Every time the local transaction payload is submitted to the RM
    // for validation and possible commitment, the time it took to
    // perform the submission is added here. Thus as a single
    // transaction may be submitted multiple times, so there may be
    // multiple elements in this list. Nested transactions never appear
    // here as nested transactions are client-side only.
    Submissions []time.Duration
    // The id of the transaction.
    TxnId *common.TxnId
}

A Stats object is created for each root transaction and shared with any nested transactions. It records some details about how the transaction progressed.

type Txn Uses

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

A Txn object holds the state of the current transaction and is supplied to your transaction functions. Through this object you can interact with the GoshawkDB object store.

func (*Txn) CreateObject Uses

func (txn *Txn) CreateObject(value []byte, references ...ObjectRef) (ObjectRef, error)

Create a new object and set its value and references. This method takes copies of both the value and the references so if you modify either after calling this method, your modifications will not take effect. If the error is Restart, you should return Restart as an error in the transaction. The ObjectRef returned will contain the ReadWrite capability and the client is granted the full ReadWrite capability on the object for the lifetime of the client connection.

func (*Txn) GetObject Uses

func (txn *Txn) GetObject(objRef ObjectRef) (ObjectRef, error)

Fetches the ObjectRef specified by this ObjectRef. Note this will fail unless the client has already navigated the object graph at least as far as any object that has a reference to the object id. This method is not normally necessary: it is generally preferred to use the References of objects to navigate. This method is useful if you are storing ObjectRefs outside the database object graph and can guarantee the connection you're using will have already reached the object in question.

func (*Txn) GetRootObjects Uses

func (txn *Txn) GetRootObjects() (map[string]ObjectRef, error)

Returns the database Root Objects. The Root Objects for each client are defined by the cluster configuration represent the roots of the object graphs. For an object to be reachable, there must be a readable path to it from a Root Object. If an error is returned, the current transaction should immediately be restarted (return the error Restart)

func (*Txn) String Uses

func (txn *Txn) String() string

type TxnFunResult Uses

type TxnFunResult uint8
const (
    // If you return Retry as the result (not error) of a transaction
    // then a retry transaction is performed.
    Retry TxnFunResult = iota
    // If the transaction detects that it needs to be restarted as soon
    // as possible then all methods on Object will return Restart as an
    // error. You should detect this and return Restart as an error in
    // the transaction function, allowing the transaction function to
    // be restarted promptly.
    Restart TxnFunResult = iota
)

func (TxnFunResult) Error Uses

func (tfr TxnFunResult) Error() string

Package client imports 17 packages (graph) and is imported by 1 packages. Updated 2016-11-19. Refresh now. Tools for package owners.