README
¶
GoshawkDB Go Client
This repo contains the Go client for GoshawkDB. It is go gettable with:
go get goshawkdb.io/client
Please see the documentation
Documentation
¶
Overview ¶
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 ¶
- type Capability
- type Connection
- type ObjectRef
- func (objRef ObjectRef) GrantCapability(capability Capability) ObjectRef
- func (objRef ObjectRef) Id() *common.VarUUId
- func (objRef ObjectRef) ObjectCapability() Capability
- func (objRef ObjectRef) RefCapability() Capability
- func (o ObjectRef) References() ([]ObjectRef, error)
- func (a ObjectRef) ReferencesSameAs(b ObjectRef) bool
- func (o ObjectRef) Set(value []byte, references ...ObjectRef) error
- func (objRef ObjectRef) String() string
- func (o ObjectRef) Value() ([]byte, error)
- func (o ObjectRef) ValueReferences() ([]byte, []ObjectRef, error)
- func (o ObjectRef) Version() (*common.TxnId, error)
- type Stats
- type Txn
- type TxnFunResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capability ¶
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 ¶
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 ¶
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 ¶
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 ¶
func (conn *Connection) Shutdown()
Shutdown the connection. This will block until the connection is closed.
type ObjectRef ¶
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 ¶
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 ¶
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 ¶
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 ¶
func (objRef ObjectRef) RefCapability() Capability
Reveal which capabilities this ObjectRef contains.
func (ObjectRef) References ¶
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 ¶
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 ¶
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) Value ¶
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 ¶
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.
type Stats ¶
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 ¶
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 ¶
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 ¶
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 ¶
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)
type TxnFunResult ¶
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 ¶
func (tfr TxnFunResult) Error() string
Source Files