README
¶
boltx 
This package contains a collection of tools for BoltDB. It tries to simplify the handling of models in a BoltDB bucket without being too opinionated.
It's basically assumes that models implement encoding.BinaryMarshaler and encoding.BinaryUnmarshaler from Go's
standard library.
type model struct { ... }
func (m *model) MarshalBinary() ([]byte, error) { ... }
func (m *model) UnmarshalBinary([]byte) (error) { ... }
Those methods should handle the (de)serialization of the model. The interfaces are than used by the functions of this package to store and load models.
model := &model{}
boltx.PutModel(bucket, []byte("key"), model)
boltx.GetModel(bucket, []byte("key"), model)
Queue
The Queue helper implements a queue (single-ended) on a bucket. It's persistent and safe to used with
multiple goroutines.
queue := boltx.NewQueue(db, []byte("queue-test"))
queue.EnqueueModel(&model{"item"})
model := &model{}
queue.DequeueModel(model)
log.Println(model)
Deque
The Deque helper implements a deque (double-ended queue) on a bucket. It's persistent and safe to use with
multiple goroutines.
deque := boltx.NewDeque(db, []byte("deque-test"))
go func () {
deque.EnqueueModelBack(&model{"item"})
}()
model := &model{}
deque.DequeueModelFront(model)
log.Println(model)
Documentation
¶
Overview ¶
Package boltx contains a collection of tools for [BoltDB](https://github.com/boltdb/bolt). It tries to simplify the handling of models in a BoltDB bucket without being too opinionated.
It's basically assumes that models implement `encoding.BinaryMarshaler` and `encoding.BinaryUnmarshaler` from Go's standard library.
type model struct { ... }
func (m *model) MarshalBinary() ([]byte, error) { ... }
func (m *model) UnmarshalBinary([]byte) (error) { ... }
Those methods should handle the (de)serialization of the model. The interfaces are than used by the functions of this package to store and load models.
model := &model{}
boltx.PutModel(bucket, []byte("key"), model)
boltx.GetModel(bucket, []byte("key"), model)
Index ¶
- Constants
- Variables
- func BucketSize(db *bolt.DB, name []byte) int
- func DeleteFromBucket(db *bolt.DB, name, key []byte) error
- func ForEach(bucket *bolt.Bucket, prototype encoding.BinaryUnmarshaler, ...) ([]byte, interface{}, error)
- func GetFromBucket(db *bolt.DB, name, key []byte) []byte
- func GetModel(bucket *bolt.Bucket, key []byte, model encoding.BinaryUnmarshaler) (bool, error)
- func GetModelFromBucket(db *bolt.DB, name, key []byte, model encoding.BinaryUnmarshaler) (bool, error)
- func Pop(tx *bolt.Tx, name []byte, position *Position) []byte
- func PopModelOrWait(tx *bolt.Tx, name []byte, position *Position, model encoding.BinaryUnmarshaler, ...) error
- func PopOrWait(tx *bolt.Tx, name []byte, position *Position, session *Session) []byte
- func Push(tx *bolt.Tx, name []byte, position *Position, value, defaultKey []byte) error
- func PushAndSignal(tx *bolt.Tx, name []byte, position *Position, value, defaultKey []byte, ...) error
- func PushModelAndSignal(tx *bolt.Tx, name []byte, position *Position, model encoding.BinaryMarshaler, ...) error
- func PutInBucket(db *bolt.DB, name, key, value []byte) error
- func PutModel(bucket *bolt.Bucket, key []byte, model encoding.BinaryMarshaler) error
- func PutModelInBucket(db *bolt.DB, name, key []byte, model encoding.BinaryMarshaler) error
- type Action
- type Deque
- func (d *Deque) DequeueModelBack(model encoding.BinaryUnmarshaler) error
- func (d *Deque) DequeueModelFront(model encoding.BinaryUnmarshaler) error
- func (d *Deque) EnqueueModelBack(model encoding.BinaryMarshaler) error
- func (d *Deque) EnqueueModelFront(model encoding.BinaryMarshaler) error
- func (d *Deque) Size() int
- type Position
- type Queue
- type Session
Constants ¶
const ( // ActionContinue tells the iterator to jump to the next element. ActionContinue = 1 << iota // ActionReturn indicates that the iteration should be stopped and the current element should be returned. ActionReturn = 1 << iota // ActionUpdate tells the iterator that the current element has been changed and should be updated. ActionUpdate = 1 << iota // ActionDelete tells the iterator to delete the current element. ActionDelete = 1 << iota )
Variables ¶
var ( // DefaultUint64QueueKey defines the default key for a queue with uint64 keys. DefaultUint64QueueKey = []byte{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00} // DefaultUint64DequeKey defines the default key for a deque (double-ended queue) with uint64 keys. DefaultUint64DequeKey = big.NewInt(0).SetUint64(math.MaxUint64 / 2).Bytes() // PositionFront specifies the front of a queue or deque. PositionFront = &Position{delta: -1, fn: func(cursor *bolt.Cursor) ([]byte, []byte) { return cursor.First() }} // PositionBack specifies the back of a queue or deque. PositionBack = &Position{delta: 1, fn: func(cursor *bolt.Cursor) ([]byte, []byte) { return cursor.Last() }} )
Functions ¶
func BucketSize ¶
BucketSize returns the number of key/value pairs in the provided bucket. If the bucket doesn't exists, 0 is returned.
func DeleteFromBucket ¶
DeleteFromBucket removes the provided key from the provided bucket.
func ForEach ¶
func ForEach( bucket *bolt.Bucket, prototype encoding.BinaryUnmarshaler, fn func([]byte, interface{}) (Action, error), ) ([]byte, interface{}, error)
ForEach iterates over all elements in the bucket.
func GetFromBucket ¶
GetFromBucket loads the value from the provided bucket at the provided key. If the bucket and the value was found, the content is returned. Nil otherwise.
func GetModel ¶
GetModel loads the value from the provided bucket at the provided key and unmarshals it into the provided model. If the value was found, true is returned. False otherwise.
func GetModelFromBucket ¶
func GetModelFromBucket(db *bolt.DB, name, key []byte, model encoding.BinaryUnmarshaler) (bool, error)
GetModelFromBucket loads the value from the provided bucket at the provided key and unmarshals it into the provided model. If the bucket and the value was found, true is returned. False otherwise.
func Pop ¶
Pop removes and returns the value at the provided position in the provided bucket. If the bucket is empty, nil is returned.
func PopModelOrWait ¶
func PopModelOrWait( tx *bolt.Tx, name []byte, position *Position, model encoding.BinaryUnmarshaler, session *Session, ) error
PopModelOrWait behaves like PopOrWair, but handels the model unmarshaling.
func PopOrWait ¶
PopOrWait tries to pop a value from the provided bucket at the provided position. If the bucket is empty, the provided transaction is stored in the provided session and the function blocks until a value is inserted into the bucket. Insert-transactions should be started with session.Update.
func Push ¶
Push inserts the provided value at the provided position in the provided bucket. If the bucket is empty, the provided defaultKey is used.
func PushAndSignal ¶
func PushAndSignal(tx *bolt.Tx, name []byte, position *Position, value, defaultKey []byte, session *Session) error
PushAndSignal pushes the the provided value at the provided position in the provided bucket. Afterwards an update is siganled through the provided session.
func PushModelAndSignal ¶
func PushModelAndSignal( tx *bolt.Tx, name []byte, position *Position, model encoding.BinaryMarshaler, defaultKey []byte, session *Session, ) error
PushModelAndSignal behaves like PushAndSignal, but handels the model marshaling.
func PutInBucket ¶
PutInBucket creates the bucket with the provided name if it's not existing and stores the provided value under the provided key.
func PutModel ¶
PutModel marshals the provided model and stores it in the provided bucket under the provided key.
func PutModelInBucket ¶
PutModelInBucket marshals the provided model, creates the bucket with the provided name if it's not existing and stores the marshalled model under the provided key.
Types ¶
type Action ¶
type Action int
Action indicates how an element should be handled after the iterator went over it.
type Deque ¶
type Deque struct {
// contains filtered or unexported fields
}
Deque defines a double-ended queue on a bucket. It's persistent and safe to use with multiple goroutines.
deque := boltx.NewDeque(db, []byte("deque-test"))
go func () {
deque.EnqueueModelBack(&model{"item"})
}()
model := &model{}
deque.DequeueModelFront(model)
log.Println(model)
func (*Deque) DequeueModelBack ¶
func (d *Deque) DequeueModelBack(model encoding.BinaryUnmarshaler) error
DequeueModelBack gets the value from the back of the deque, unmarshals it into the provided model and removes it. If the deque is empty the call blocks until an element is enqueued.
func (*Deque) DequeueModelFront ¶
func (d *Deque) DequeueModelFront(model encoding.BinaryUnmarshaler) error
DequeueModelFront gets the value from the front of the deque, unmarshals it into the provided model and removes it. If the deque is empty the call blocks until an element is enqueued.
func (*Deque) EnqueueModelBack ¶
func (d *Deque) EnqueueModelBack(model encoding.BinaryMarshaler) error
EnqueueModelBack puts the provided model to the back of the deque.
func (*Deque) EnqueueModelFront ¶
func (d *Deque) EnqueueModelFront(model encoding.BinaryMarshaler) error
EnqueueModelFront puts the provided model to the front of the deque.
type Position ¶
type Position struct {
// contains filtered or unexported fields
}
Position defines a position in a queue or deque.
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue defines a single-ended queue on a bucket. It's persistent and safe to use with multiple goroutines.
queue := boltx.NewQueue(db, []byte("queue-test"))
queue.EnqueueModel(&model{"item"})
model := &model{}
queue.DequeueModel(model)
log.Println(model)
func (*Queue) DequeueModel ¶
func (q *Queue) DequeueModel(model encoding.BinaryUnmarshaler) error
DequeueModel gets the value from the front of the deque, unmarshals it into the provided model and removes it. If the deque is empty the call blocks until an element is enqueued.
func (*Queue) EnqueueModel ¶
func (q *Queue) EnqueueModel(model encoding.BinaryMarshaler) error
EnqueueModel puts the provided model to the back of the queue.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session defines a update session. It can be used to re-used transactions that are waiting on an update.
func NewSession ¶
NewSession returns a new initialized session.
Source Files