gophia

package module
v0.0.0-...-52fbb35 Latest Latest
Warning

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

 Go to latest Published: Sep 26, 2013 License: BSD-2-Clause Imports: 6 Imported by: 0

README

gophia v0.1.3

Gophia is a Go (golang) binding to the Sophia key-value database (http://sphia.org/)

Installation

Before installing Gophia, you need to install Sophia. Download it from http://sphia.org, and build.

The makefiles don't include an 'install', so you will need to manually install somewhere where Go can find the headers and the libs. Alternatively, you can set your CGO LDFLAGS and CFLAGS like so:

# My Sophia files installed to /usr/local/src/sophia
export CGO_LDFLAGS="-L/usr/local/src/sophia/db"
export CGO_CFLAGS="-I/usr/local/src/sophia/db"

Once Sophia is installed, Gophia can be installed with go get github.com/craigmj/gophia

Very Important

Sophia does not currently appear to support multi-threading. I'm not totally sure what is meant by this, but it seems to be that deep trouble will occur if using Gophia from multiple goroutings where GOMAXPROCS > 1. We're currently investigating, and might introduce some synchronizing into Gophia to handle multi-threading. For now, assume you will need to implement your own synchronization in multi-threaded situations.

Usage

Open the database:

db, err := gophia.Open(gophia.ReadWrite | gophia.Create, "testdb")
// check for errors
defer db.Close()

You're ready to go:

// SetSS sets a string key to a string value.
db.SetSS("one","ichi")
db.SetSS("two","nichi")

fmt.Println("one is ", db.MustGetSS("one"))
fmt.Println("two is ", db.MustGetSS("two"))

You can also use a cursor:

// Without a starting key, every key-value will be returned
cur, err := db.Cursor(gophia.GTE, nil)
for cur.Fetch() {
	fmt.Println(cur.KeyS(), "=", cur.ValueS())
}
cur.Close()

Of course it's easy to delete a key-value:

db.DeleteS("one")

See the documentation for more.

Important

When a Cursor is open, no other access to the database is possible: a Cursor locks the entire db, even from other Cursors.

Therefore, you cannot do anything (Set, Delete, etc) while processing a Cursor. Also, you cannot Close the database util the Cursor is itself closed. NOT CLOSING THE DATABASE CORRUPTS THE DATABASE

In Gophia, this is simplified because you can always Close a Cursor (or Database or Environment) even if it has been previously Closed. This means that you can use the form:

cur, _ := db.Cursor(gophia.GTE, nil)
defer cur.Close()
for cur.Fetch() {
	// ...
}
cur.Close()

If for some reason you exit during the loop, your cursor will still Close, and hence the Database as well. If you continue, your Cursor is manually closed.

Gophia also offers the Database.Each method, which iterates over the key-value pairs passing each to a given function. Each takes care of closing the Cursor when it returns.

You cannot mutate the database while a Cursor is open. The Delete call in this method will throw an error.

cur, _ := db.Cursor(gophia.GTE, nil)
defer cur.Close()
for cur.Fetch() {
	err := db.Delete(cur.Key())
	// err will not be nil here - you are trying to change the 
	// database while a cursor is open
}
cur.Close()

If you don't get this behaviour, please update your Sophia installation (in an old Sophia version, this scenario caused the program to hang).

Documentation

Overview

*

  • Gophia is a Golang wrapper around the Sophia key-value database. *
  • Sophia is Copyright 2013 Dmitry Simonenko *
  • Gophia is Copyright 2013 Craig Mason-Jones. It is released under a BSD license.

Index

Constants

View Source 
const (
	GreaterThan      Order = C.SPGT
	GT                     = GreaterThan
	GreaterThanEqual       = C.SPGTE
	GTE                    = GreaterThanEqual
	LessThan               = C.SPLT
	LT                     = LessThan
	LessThanEqual          = C.SPLTE
	LTE                    = LessThanEqual
)
View Source 
const (
	ComparesEqual       int = 0
	ComparesLessThan        = -1
	ComparesGreaterThan     = 1
)
View Source 
const (
	ReadWrite Access = C.SPO_RDWR
	ReadOnly         = C.SPO_RDONLY
	Create           = C.SPO_CREAT
)

Variables

View Source 
var ErrNotFound = errors.New("Key not found")

ErrNotFound indicates that the key does not exist in the database.

View Source 
var ErrTransactionInProgress = errors.New("Transaction already in progress")

ErrTransactionInProgress returned when attempt to begin a transaction while there is already a transaction in progress.

Functions

This section is empty.

Types

type Access 

type Access C.uint32_t

type Comparator 

type Comparator func(a []byte, b []byte) int

Comparator function is used to compare keys in the database.

The function must return 0 if the keys are equal, -1 if the first key parameter is lower, and 1 if the second key parameter is lower.

See Environment.Cmp()

type Cursor 

type Cursor struct {
	unsafe.Pointer
}

Cursor iterates over key-values in a database.

func (*Cursor) Close 

func (cur *Cursor) Close() error

Close closes the cursor. If a cursor is not closed, future operations on the database can hang indefinitely.

func (*Cursor) Fetch 

func (cur *Cursor) Fetch() bool

Fetch fetches the next row for the cursor, and returns true if there is a next row, false if the cursor has reached the end of the rows.

func (*Cursor) Key 

func (cur *Cursor) Key() []byte

Key returns the current key of the cursor.

func (*Cursor) KeyLen 

func (cur *Cursor) KeyLen() int

KeyLen returns the length of the current key. It is a synonym for KeySize()

func (*Cursor) KeyS 

func (cur *Cursor) KeyS() string

KeyS returns the current key as a string.

func (*Cursor) KeySize 

func (cur *Cursor) KeySize() int

KeySize returns the size of the current key.

func (*Cursor) KeyString 

func (cur *Cursor) KeyString() string

KeyString returns the current key as a string. @deprecated Use KeyS instead

func (*Cursor) Next 

func (cur *Cursor) Next() bool

Next is identical to Fetch. It exists because it seems that Next() is more go-idiomatic.

func (*Cursor) Object 

func (cur *Cursor) Object(out interface{}) error

ValueObject returns the current object, by gob decoding the current value at the cursor. @deprecated Use ValueO instead.

func (*Cursor) Value 

func (cur *Cursor) Value() []byte

Value returns the current value of the cursor.

func (*Cursor) ValueLen 

func (cur *Cursor) ValueLen() int

ValueLen returns the length of the current value. It is a synonym for ValueSize()

func (*Cursor) ValueO 

func (cur *Cursor) ValueO(out interface{}) error

ValueO returns the current value as an object, by gob decoding the current value at the cursor.

func (*Cursor) ValueS 

func (cur *Cursor) ValueS() string

ValueS returns the current value as a string.

func (*Cursor) ValueSize 

func (cur *Cursor) ValueSize() int

ValueSize returns the length of the current value.

func (*Cursor) ValueString 

func (cur *Cursor) ValueString() string

ValueString returns the current value as a string. @deprecated Use ValueS instead

type Database 

type Database struct {
	unsafe.Pointer
	// contains filtered or unexported fields
}

Database is used for accessing a database.

func Open 

func Open(access Access, directory string) (*Database, error)

Open opens the database with the given access permissions in the given directory.

func (*Database) Begin 

func (db *Database) Begin() error

No nested transactions are supported.

func (*Database) Close 

func (db *Database) Close() error

Close closes the database and frees its associated memory. You must call Close on any database opened with Open()

func (*Database) Commit 

func (db *Database) Commit() error

Commit applies changes to a multi-statement transaction. All modifications made during the transaction are written to the log file in a single batch.

If commit failed, transaction modifications are discarded.

func (*Database) Cursor 

func (db *Database) Cursor(order Order, key []byte) (*Cursor, error)

Cursor returns a Cursor for iterating over rows in the database.

If no key is provided, the Cursor will iterate over all rows.

The order flag decides the direction of the iteration, and whether the key is included or excluded.

Iterate over values with Fetch or Next methods.

func (*Database) CursorS 

func (db *Database) CursorS(order Order, key string) (*Cursor, error)

CursorS returns a Cursor that fetches rows from the database from the given key, passed as a string. Callers must call Close() on the received Cursor.

func (*Database) CursorString 

func (db *Database) CursorString(order Order, key string) (*Cursor, error)

CursorString returns a Cursor that fetches rows from the database from the given key, passed as a string. Callers must call Close() on the received Cursor. @deprecated Use CursorS instead.

func (*Database) Delete 

func (db *Database) Delete(key []byte) error

Delete deletes the key from the database.

func (*Database) DeleteS 

func (db *Database) DeleteS(key string) error

DeleteS deletes the key from the database.

func (*Database) DeleteString 

func (db *Database) DeleteString(key string) error

DeleteString deletes the key from the database. @deprecated Use DeleteS instead.

func (*Database) Each 

func (db *Database) Each(order Order, key []byte, each func(key []byte, value []byte)) error

Each iterates through the key-values in the database, passing each to the each function. It is a convenience wrapper around a Cursor iteration.

func (*Database) Error 

func (db *Database) Error() error

Error returns any error on the database. It should not be necessary to call this method, since most methods return errors automatically.

func (*Database) Get 

func (db *Database) Get(key []byte) ([]byte, error)

Get retrieves the value for the key.

func (*Database) GetAO 

func (db *Database) GetAO(key []byte, out interface{}) error

GetAO returns on object value for a byte-array key.

func (*Database) GetObject 

func (db *Database) GetObject(key []byte, out interface{}) error

GetObject fetches a gob encoded object into the out object. @deprecated Use GetAO instead.

func (*Database) GetObjectString 

func (db *Database) GetObjectString(key string, out interface{}) error

GetObjectString retrieves a gob encoded object into the out object. It is a convenience method to facilitate working with string keys. @deprecated Use GetSO instead.

func (*Database) GetSA 

func (db *Database) GetSA(key string) ([]byte, error)

GetS retrieves an array value for a string key. It is a convenience method to simplify working with string keys.

func (*Database) GetSO 

func (db *Database) GetSO(key string, out interface{}) error

GetSO fetches a gob encoded object for a string key.

func (*Database) GetSS 

func (db *Database) GetSS(key string) (string, error)

GetSS returns a string value for a string key.

func (*Database) GetString 

func (db *Database) GetString(key string) ([]byte, error)

GetString returns a byte array value for a string key. @deprecated Use GetS instead.

func (*Database) GetStrings 

func (db *Database) GetStrings(key string) (string, error)

GetString retrieves the string value for the string key. It is a convenience function for working with strings rather than byte slices. @deprecated Use GetSS instead.

func (*Database) Has 

func (db *Database) Has(key []byte) (bool, error)

Has returns true if the database has a value for the key.

func (*Database) HasS 

func (db *Database) HasS(key string) (bool, error)

HasS returns true if the database has a value for the string key.

func (*Database) HasString 

func (db *Database) HasString(key string) (bool, error)

HasString returns true if the database has a value for the key. It is a convenience function for working with strings rather than byte slices. @deprecated Use HasS instead

func (*Database) MustGet 

func (db *Database) MustGet(key []byte) []byte

MustGet returns the value of the key, or panics on an error.

func (*Database) MustGetSA 

func (db *Database) MustGetSA(key string) []byte

MustGetSA returns the byte array value for the string key. It panics on error.

func (*Database) MustGetSS 

func (db *Database) MustGetSS(key string) string

MustGetSS returns the string value for a string key. It panics on an error.

func (*Database) MustGetString 

func (db *Database) MustGetString(key string) []byte

MustGetString returns the byte array value for the string key. It panics on error. @deprecated Use MustGetSA instead.

func (*Database) MustGetStrings 

func (db *Database) MustGetStrings(key string) string

MustGetStrings returns the string value for a string key. It panics on error. @deprecated Use MustGetSS instead.

func (*Database) MustHas 

func (db *Database) MustHas(key []byte) bool

MustHas returns true if the key exists, false otherwise. It panics in the even of error.

func (*Database) MustHasS 

func (db *Database) MustHasS(key string) bool

MustHasS returns true if the string exists, or false if it does not. It panics in the event of error.

func (*Database) MustHasString 

func (db *Database) MustHasString(key string) bool

MustHasString returns true if the string exists, or false if it does not. It panics in the event of error. @deprecated Use MustHasS instead

func (*Database) Rollback 

func (db *Database) Rollback() error

Rollback discards the changes of a multi-statement transaction. All modifications made during the transaction are not written to the log file.

func (*Database) Set 

func (db *Database) Set(key, value []byte) error

Set sets the value of the key.

func (*Database) SetAO 

func (db *Database) SetAO(key []byte, value interface{}) error

SetAO sets a byte array key to an object value.

func (*Database) SetObject 

func (db *Database) SetObject(key []byte, value interface{}) error

SetObject will gob encode the object and store it with the key. @deprecated Use SetAO instead

func (*Database) SetObjectString 

func (db *Database) SetObjectString(key string, value interface{}) error

SetObjectString will gob encode the object and store it with the key. This is a convenience method to facilitate working with string keys. @deprecated Prefer SetSO

func (*Database) SetSA 

func (db *Database) SetSA(key string, value []byte) error

SetSA sets a string key to a byte array value.

func (*Database) SetSO 

func (db *Database) SetSO(key string, value interface{}) error

SetSO sets a string key to an object value.

func (*Database) SetSS 

func (db *Database) SetSS(key, value string) error

SetSS sets a string key to a string value

func (*Database) SetString 

func (db *Database) SetString(key string, value []byte) error

SetString sets the byte-slice value of the string key. It is a convenience function for working with string keys rather than byte slices. @deprecated Use SetSA instead

func (*Database) SetStrings 

func (db *Database) SetStrings(key, value string) error

SetStrings sets the value of the key. It is a convenience function for working with strings rather than byte slices. @deprecated Use SetSS instead

type Environment 

type Environment struct {
	unsafe.Pointer
}

Environment is used to configure the database before opening.

func NewEnvironment 

func NewEnvironment() (*Environment, error)

NewEnvironment creates a new environment for opening a database. Receivers must call Close() on the returned Environment.

func (*Environment) Close 

func (env *Environment) Close() error

Close closes the enviroment and frees its associated memory. You must call Close on any Environment created with NewEnvironment.

func (*Environment) Cmp 

func (env *Environment) Cmp(cmp Comparator) error

Cmp sets the database comparator function to use for ordering keys.

The function must return 0 if the keys are equal, -1 if the first key parameter is lower, and 1 if the second key parameter is lower.

func (*Environment) Dir 

func (env *Environment) Dir(access Access, directory string) error

Dir sets the access mode and the directory for the database.

func (*Environment) Error 

func (env *Environment) Error() error

Error returns any error on the Environment. It should not be necessary to call this method, since the Go methods all return with errors themselves.

func (*Environment) GC 

func (env *Environment) GC(enabled bool) error

GC turns the garbage collector on or off.

func (*Environment) GCF 

func (env *Environment) GCF(factor float64) error

GCF sets database garbage collector factor value, which is used to determine when to start the GC.

For example: factor 0.5 means that all 'live' pages from any db file will be copied to new db when half or fewer of them are left.

This option can be tweaked for performance.

func (*Environment) Grow 

func (env *Environment) Grow(newsize uint32, newFactor float64) error

Grow sets the initial new size and resize factor for new database files. The values are used while the database extends during a merge.

This option can be tweaked for performance.

func (*Environment) Merge 

func (env *Environment) Merge(merge bool) error

Merge sets whether to launch a merger thread during Open().

func (*Environment) MergeWM 

func (env *Environment) MergeWM(watermark uint32) error

MergeWM sets the database merge watermark value.

When the database update count reaches this value, it notifies the merger thread to create a new epoch and start merging in-memory keys.

This option can be tweaked for performance.

func (*Environment) Open 

func (env *Environment) Open() (*Database, error)

Open() opens the database that has been configured in the Environment. At a minimum, it should be necessary to call Dir() on the Environment to specify the directory for the database.

func (*Environment) Page 

func (env *Environment) Page(count int) error

Page sets the max key count in a single page for the database. This option can be tweaked for performance.

type Order 

type Order C.uint32_t

Order of items in an iteration

Source Files

View all Source files

Jump to

Keyboard shortcuts

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