+++ /dev/null
-// Copyright (c) 2015-2016 The btcsuite developers
-// Use of this source code is governed by an ISC
-// license that can be found in the LICENSE file.
-
-// Parts of this interface were inspired heavily by the excellent boltdb project
-// at https://github.com/boltdb/bolt by Ben B. Johnson.
-
-package database
-
-import (
- "github.com/btcsuite/btcd/chaincfg/chainhash"
- "github.com/btcsuite/btcutil"
-)
-
-// Cursor represents a cursor over key/value pairs and nested buckets of a
-// bucket.
-//
-// Note that open cursors are not tracked on bucket changes and any
-// modifications to the bucket, with the exception of Cursor.Delete, invalidates
-// the cursor. After invalidation, the cursor must be repositioned, or the keys
-// and values returned may be unpredictable.
-type Cursor interface {
- // Bucket returns the bucket the cursor was created for.
- Bucket() Bucket
-
- // Delete removes the current key/value pair the cursor is at without
- // invalidating the cursor.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrIncompatibleValue if attempted when the cursor points to a
- // nested bucket
- // - ErrTxNotWritable if attempted against a read-only transaction
- // - ErrTxClosed if the transaction has already been closed
- Delete() error
-
- // First positions the cursor at the first key/value pair and returns
- // whether or not the pair exists.
- First() bool
-
- // Last positions the cursor at the last key/value pair and returns
- // whether or not the pair exists.
- Last() bool
-
- // Next moves the cursor one key/value pair forward and returns whether
- // or not the pair exists.
- Next() bool
-
- // Prev moves the cursor one key/value pair backward and returns whether
- // or not the pair exists.
- Prev() bool
-
- // Seek positions the cursor at the first key/value pair that is greater
- // than or equal to the passed seek key. Returns whether or not the
- // pair exists.
- Seek(seek []byte) bool
-
- // Key returns the current key the cursor is pointing to.
- Key() []byte
-
- // Value returns the current value the cursor is pointing to. This will
- // be nil for nested buckets.
- Value() []byte
-}
-
-// Bucket represents a collection of key/value pairs.
-type Bucket interface {
- // Bucket retrieves a nested bucket with the given key. Returns nil if
- // the bucket does not exist.
- Bucket(key []byte) Bucket
-
- // CreateBucket creates and returns a new nested bucket with the given
- // key.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBucketExists if the bucket already exists
- // - ErrBucketNameRequired if the key is empty
- // - ErrIncompatibleValue if the key is otherwise invalid for the
- // particular implementation
- // - ErrTxNotWritable if attempted against a read-only transaction
- // - ErrTxClosed if the transaction has already been closed
- CreateBucket(key []byte) (Bucket, error)
-
- // CreateBucketIfNotExists creates and returns a new nested bucket with
- // the given key if it does not already exist.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBucketNameRequired if the key is empty
- // - ErrIncompatibleValue if the key is otherwise invalid for the
- // particular implementation
- // - ErrTxNotWritable if attempted against a read-only transaction
- // - ErrTxClosed if the transaction has already been closed
- CreateBucketIfNotExists(key []byte) (Bucket, error)
-
- // DeleteBucket removes a nested bucket with the given key. This also
- // includes removing all nested buckets and keys under the bucket being
- // deleted.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBucketNotFound if the specified bucket does not exist
- // - ErrTxNotWritable if attempted against a read-only transaction
- // - ErrTxClosed if the transaction has already been closed
- DeleteBucket(key []byte) error
-
- // ForEach invokes the passed function with every key/value pair in the
- // bucket. This does not include nested buckets or the key/value pairs
- // within those nested buckets.
- //
- // WARNING: It is not safe to mutate data while iterating with this
- // method. Doing so may cause the underlying cursor to be invalidated
- // and return unexpected keys and/or values.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrTxClosed if the transaction has already been closed
- //
- // NOTE: The slices returned by this function are only valid during a
- // transaction. Attempting to access them after a transaction has ended
- // results in undefined behavior. Additionally, the slices must NOT
- // be modified by the caller. These constraints prevent additional data
- // copies and allows support for memory-mapped database implementations.
- ForEach(func(k, v []byte) error) error
-
- // ForEachBucket invokes the passed function with the key of every
- // nested bucket in the current bucket. This does not include any
- // nested buckets within those nested buckets.
- //
- // WARNING: It is not safe to mutate data while iterating with this
- // method. Doing so may cause the underlying cursor to be invalidated
- // and return unexpected keys and/or values.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrTxClosed if the transaction has already been closed
- //
- // NOTE: The keys returned by this function are only valid during a
- // transaction. Attempting to access them after a transaction has ended
- // results in undefined behavior. This constraint prevents additional
- // data copies and allows support for memory-mapped database
- // implementations.
- ForEachBucket(func(k []byte) error) error
-
- // Cursor returns a new cursor, allowing for iteration over the bucket's
- // key/value pairs and nested buckets in forward or backward order.
- //
- // You must seek to a position using the First, Last, or Seek functions
- // before calling the Next, Prev, Key, or Value functions. Failure to
- // do so will result in the same return values as an exhausted cursor,
- // which is false for the Prev and Next functions and nil for Key and
- // Value functions.
- Cursor() Cursor
-
- // Writable returns whether or not the bucket is writable.
- Writable() bool
-
- // Put saves the specified key/value pair to the bucket. Keys that do
- // not already exist are added and keys that already exist are
- // overwritten.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrKeyRequired if the key is empty
- // - ErrIncompatibleValue if the key is the same as an existing bucket
- // - ErrTxNotWritable if attempted against a read-only transaction
- // - ErrTxClosed if the transaction has already been closed
- //
- // NOTE: The slices passed to this function must NOT be modified by the
- // caller. This constraint prevents the requirement for additional data
- // copies and allows support for memory-mapped database implementations.
- Put(key, value []byte) error
-
- // Get returns the value for the given key. Returns nil if the key does
- // not exist in this bucket. An empty slice is returned for keys that
- // exist but have no value assigned.
- //
- // NOTE: The value returned by this function is only valid during a
- // transaction. Attempting to access it after a transaction has ended
- // results in undefined behavior. Additionally, the value must NOT
- // be modified by the caller. These constraints prevent additional data
- // copies and allows support for memory-mapped database implementations.
- Get(key []byte) []byte
-
- // Delete removes the specified key from the bucket. Deleting a key
- // that does not exist does not return an error.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrKeyRequired if the key is empty
- // - ErrIncompatibleValue if the key is the same as an existing bucket
- // - ErrTxNotWritable if attempted against a read-only transaction
- // - ErrTxClosed if the transaction has already been closed
- Delete(key []byte) error
-}
-
-// BlockRegion specifies a particular region of a block identified by the
-// specified hash, given an offset and length.
-type BlockRegion struct {
- Hash *chainhash.Hash
- Offset uint32
- Len uint32
-}
-
-// Tx represents a database transaction. It can either by read-only or
-// read-write. The transaction provides a metadata bucket against which all
-// read and writes occur.
-//
-// As would be expected with a transaction, no changes will be saved to the
-// database until it has been committed. The transaction will only provide a
-// view of the database at the time it was created. Transactions should not be
-// long running operations.
-type Tx interface {
- // Metadata returns the top-most bucket for all metadata storage.
- Metadata() Bucket
-
- // StoreBlock stores the provided block into the database. There are no
- // checks to ensure the block connects to a previous block, contains
- // double spends, or any additional functionality such as transaction
- // indexing. It simply stores the block in the database.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBlockExists when the block hash already exists
- // - ErrTxNotWritable if attempted against a read-only transaction
- // - ErrTxClosed if the transaction has already been closed
- //
- // Other errors are possible depending on the implementation.
- StoreBlock(block *btcutil.Block) error
-
- // HasBlock returns whether or not a block with the given hash exists
- // in the database.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrTxClosed if the transaction has already been closed
- //
- // Other errors are possible depending on the implementation.
- HasBlock(hash *chainhash.Hash) (bool, error)
-
- // HasBlocks returns whether or not the blocks with the provided hashes
- // exist in the database.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrTxClosed if the transaction has already been closed
- //
- // Other errors are possible depending on the implementation.
- HasBlocks(hashes []chainhash.Hash) ([]bool, error)
-
- // FetchBlockHeader returns the raw serialized bytes for the block
- // header identified by the given hash. The raw bytes are in the format
- // returned by Serialize on a wire.BlockHeader.
- //
- // It is highly recommended to use this function (or FetchBlockHeaders)
- // to obtain block headers over the FetchBlockRegion(s) functions since
- // it provides the backend drivers the freedom to perform very specific
- // optimizations which can result in significant speed advantages when
- // working with headers.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBlockNotFound if the requested block hash does not exist
- // - ErrTxClosed if the transaction has already been closed
- // - ErrCorruption if the database has somehow become corrupted
- //
- // NOTE: The data returned by this function is only valid during a
- // database transaction. Attempting to access it after a transaction
- // has ended results in undefined behavior. This constraint prevents
- // additional data copies and allows support for memory-mapped database
- // implementations.
- FetchBlockHeader(hash *chainhash.Hash) ([]byte, error)
-
- // FetchBlockHeaders returns the raw serialized bytes for the block
- // headers identified by the given hashes. The raw bytes are in the
- // format returned by Serialize on a wire.BlockHeader.
- //
- // It is highly recommended to use this function (or FetchBlockHeader)
- // to obtain block headers over the FetchBlockRegion(s) functions since
- // it provides the backend drivers the freedom to perform very specific
- // optimizations which can result in significant speed advantages when
- // working with headers.
- //
- // Furthermore, depending on the specific implementation, this function
- // can be more efficient for bulk loading multiple block headers than
- // loading them one-by-one with FetchBlockHeader.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBlockNotFound if any of the request block hashes do not exist
- // - ErrTxClosed if the transaction has already been closed
- // - ErrCorruption if the database has somehow become corrupted
- //
- // NOTE: The data returned by this function is only valid during a
- // database transaction. Attempting to access it after a transaction
- // has ended results in undefined behavior. This constraint prevents
- // additional data copies and allows support for memory-mapped database
- // implementations.
- FetchBlockHeaders(hashes []chainhash.Hash) ([][]byte, error)
-
- // FetchBlock returns the raw serialized bytes for the block identified
- // by the given hash. The raw bytes are in the format returned by
- // Serialize on a wire.MsgBlock.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBlockNotFound if the requested block hash does not exist
- // - ErrTxClosed if the transaction has already been closed
- // - ErrCorruption if the database has somehow become corrupted
- //
- // NOTE: The data returned by this function is only valid during a
- // database transaction. Attempting to access it after a transaction
- // has ended results in undefined behavior. This constraint prevents
- // additional data copies and allows support for memory-mapped database
- // implementations.
- FetchBlock(hash *chainhash.Hash) ([]byte, error)
-
- // FetchBlocks returns the raw serialized bytes for the blocks
- // identified by the given hashes. The raw bytes are in the format
- // returned by Serialize on a wire.MsgBlock.
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBlockNotFound if the any of the requested block hashes do not
- // exist
- // - ErrTxClosed if the transaction has already been closed
- // - ErrCorruption if the database has somehow become corrupted
- //
- // NOTE: The data returned by this function is only valid during a
- // database transaction. Attempting to access it after a transaction
- // has ended results in undefined behavior. This constraint prevents
- // additional data copies and allows support for memory-mapped database
- // implementations.
- FetchBlocks(hashes []chainhash.Hash) ([][]byte, error)
-
- // FetchBlockRegion returns the raw serialized bytes for the given
- // block region.
- //
- // For example, it is possible to directly extract Bitcoin transactions
- // and/or scripts from a block with this function. Depending on the
- // backend implementation, this can provide significant savings by
- // avoiding the need to load entire blocks.
- //
- // The raw bytes are in the format returned by Serialize on a
- // wire.MsgBlock and the Offset field in the provided BlockRegion is
- // zero-based and relative to the start of the block (byte 0).
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBlockNotFound if the requested block hash does not exist
- // - ErrBlockRegionInvalid if the region exceeds the bounds of the
- // associated block
- // - ErrTxClosed if the transaction has already been closed
- // - ErrCorruption if the database has somehow become corrupted
- //
- // NOTE: The data returned by this function is only valid during a
- // database transaction. Attempting to access it after a transaction
- // has ended results in undefined behavior. This constraint prevents
- // additional data copies and allows support for memory-mapped database
- // implementations.
- FetchBlockRegion(region *BlockRegion) ([]byte, error)
-
- // FetchBlockRegions returns the raw serialized bytes for the given
- // block regions.
- //
- // For example, it is possible to directly extract Bitcoin transactions
- // and/or scripts from various blocks with this function. Depending on
- // the backend implementation, this can provide significant savings by
- // avoiding the need to load entire blocks.
- //
- // The raw bytes are in the format returned by Serialize on a
- // wire.MsgBlock and the Offset fields in the provided BlockRegions are
- // zero-based and relative to the start of the block (byte 0).
- //
- // The interface contract guarantees at least the following errors will
- // be returned (other implementation-specific errors are possible):
- // - ErrBlockNotFound if any of the requested block hashed do not
- // exist
- // - ErrBlockRegionInvalid if one or more region exceed the bounds of
- // the associated block
- // - ErrTxClosed if the transaction has already been closed
- // - ErrCorruption if the database has somehow become corrupted
- //
- // NOTE: The data returned by this function is only valid during a
- // database transaction. Attempting to access it after a transaction
- // has ended results in undefined behavior. This constraint prevents
- // additional data copies and allows support for memory-mapped database
- // implementations.
- FetchBlockRegions(regions []BlockRegion) ([][]byte, error)
-
- // ******************************************************************
- // Methods related to both atomic metadata storage and block storage.
- // ******************************************************************
-
- // Commit commits all changes that have been made to the metadata or
- // block storage. Depending on the backend implementation this could be
- // to a cache that is periodically synced to persistent storage or
- // directly to persistent storage. In any case, all transactions which
- // are started after the commit finishes will include all changes made
- // by this transaction. Calling this function on a managed transaction
- // will result in a panic.
- Commit() error
-
- // Rollback undoes all changes that have been made to the metadata or
- // block storage. Calling this function on a managed transaction will
- // result in a panic.
- Rollback() error
-}
-
-// DB provides a generic interface that is used to store bitcoin blocks and
-// related metadata. This interface is intended to be agnostic to the actual
-// mechanism used for backend data storage. The RegisterDriver function can be
-// used to add a new backend data storage method.
-//
-// This interface is divided into two distinct categories of functionality.
-//
-// The first category is atomic metadata storage with bucket support. This is
-// accomplished through the use of database transactions.
-//
-// The second category is generic block storage. This functionality is
-// intentionally separate because the mechanism used for block storage may or
-// may not be the same mechanism used for metadata storage. For example, it is
-// often more efficient to store the block data as flat files while the metadata
-// is kept in a database. However, this interface aims to be generic enough to
-// support blocks in the database too, if needed by a particular backend.
-type DB interface {
- // Type returns the database driver type the current database instance
- // was created with.
- Type() string
-
- // Begin starts a transaction which is either read-only or read-write
- // depending on the specified flag. Multiple read-only transactions
- // can be started simultaneously while only a single read-write
- // transaction can be started at a time. The call will block when
- // starting a read-write transaction when one is already open.
- //
- // NOTE: The transaction must be closed by calling Rollback or Commit on
- // it when it is no longer needed. Failure to do so can result in
- // unclaimed memory and/or inablity to close the database due to locks
- // depending on the specific database implementation.
- Begin(writable bool) (Tx, error)
-
- // View invokes the passed function in the context of a managed
- // read-only transaction. Any errors returned from the user-supplied
- // function are returned from this function.
- //
- // Calling Rollback or Commit on the transaction passed to the
- // user-supplied function will result in a panic.
- View(fn func(tx Tx) error) error
-
- // Update invokes the passed function in the context of a managed
- // read-write transaction. Any errors returned from the user-supplied
- // function will cause the transaction to be rolled back and are
- // returned from this function. Otherwise, the transaction is committed
- // when the user-supplied function returns a nil error.
- //
- // Calling Rollback or Commit on the transaction passed to the
- // user-supplied function will result in a panic.
- Update(fn func(tx Tx) error) error
-
- // Close cleanly shuts down the database and syncs all data. It will
- // block until all database transactions have been finalized (rolled
- // back or committed).
- Close() error
-}
OSDN Git Service
