README
¶
mydb
my database practice (B+tree, mmap, transaction)
代码阅读顺序
page -> node -> freelist -> cursor -> tx -> bucket -> db
关于mmap相关代码，可以去bolt那边看bolt_*相关的文件，因为都是平台相关代码，所以就不拷过来，
这里基本把核心的都看了，注释也翻译完了
参考
Documentation
¶
Index ¶
- Constants
- Variables
- type Bucket
- func (b *Bucket) Bucket(name []byte) *Bucket
- func (b *Bucket) CreateBucket(key []byte) (*Bucket, error)
- func (b *Bucket) CreateBucketIfNotExists(key []byte) (*Bucket, error)
- func (b *Bucket) Cursor() *Cursor
- func (b *Bucket) Delete(key []byte) error
- func (b *Bucket) DeleteBucket(key []byte) error
- func (b *Bucket) ForEach(fn func(k, v []byte) error) error
- func (b *Bucket) Get(key []byte) []byte
- func (b *Bucket) NextSequence() (uint64, error)
- func (b *Bucket) Put(key []byte, value []byte) error
- func (b *Bucket) Root() pgid
- func (b *Bucket) Sequence() uint64
- func (b *Bucket) SetSequence(v uint64) error
- func (b *Bucket) Stats() BucketStats
- func (b *Bucket) Tx() *Tx
- func (b *Bucket) Writable() bool
- type BucketStats
- type Cursor
- func (c *Cursor) Bucket() *Bucket
- func (c *Cursor) Delete() error
- func (c *Cursor) First() (key []byte, value []byte)
- func (c *Cursor) Last() (key []byte, value []byte)
- func (c *Cursor) Next() (key []byte, value []byte)
- func (c *Cursor) Prev() (key []byte, value []byte)
- func (c *Cursor) Seek(seek []byte) (key []byte, value []byte)
- type DB
- func (db *DB) Batch(fn func(*Tx) error) error
- func (db *DB) Begin(writable bool) (*Tx, error)
- func (db *DB) Close() error
- func (db *DB) GoString() string
- func (db *DB) Info() *Info
- func (db *DB) IsReadOnly() bool
- func (db *DB) Path() string
- func (db *DB) Stats() Stats
- func (db *DB) String() string
- func (db *DB) Sync() error
- func (db *DB) Update(fn func(*Tx) error) error
- func (db *DB) View(fn func(*Tx) error) error
- type Info
- type Options
- type PageInfo
- type Stats
- type Tx
- func (tx *Tx) Bucket(name []byte) *Bucket
- func (tx *Tx) Check() <-chan error
- func (tx *Tx) Commit() error
- func (tx *Tx) Copy(w io.Writer) error
- func (tx *Tx) CopyFile(path string, mode os.FileMode) error
- func (tx *Tx) CreateBucket(name []byte) (*Bucket, error)
- func (tx *Tx) CreateBucketIfNotExists(name []byte) (*Bucket, error)
- func (tx *Tx) Cursor() *Cursor
- func (tx *Tx) DB() *DB
- func (tx *Tx) DeleteBucket(name []byte) error
- func (tx *Tx) ForEach(fn func(name []byte, b *Bucket) error) error
- func (tx *Tx) ID() int
- func (tx *Tx) OnCommit(fn func())
- func (tx *Tx) Page(id int) (*PageInfo, error)
- func (tx *Tx) Rollback() error
- func (tx *Tx) Size() int64
- func (tx *Tx) Stats() TxStats
- func (tx *Tx) Writable() bool
- func (tx *Tx) WriteTo(w io.Writer) (n int64, err error)
- type TxStats
Constants ¶
const ( // MaxKeySize 一个键的最大字节数 MaxKeySize = 32768 // MaxValueSize 一个值的最大字节数 MaxValueSize = (1 << 31) - 2 )
const ( DefaultMaxBatchSize int = 1000 DefaultMaxBatchDelay = 10 * time.Millisecond DefaultAllocSize = 16 * 1024 * 1024 )
如果没有设置到DB实例，那就用下面的默认值
const DefaultFillPercent = 0.5
DefaultFillPercent 默认拆分一个页的百分比阀值， 这个可以通过Bucket.FillPercent来修改
const IgnoreNoSync = runtime.GOOS == "openbsd"
IgnoreNoSync 表示当要同步改动到文件时，DB里面的NoSync字段是否被忽略 因为有些操作系统例如OpenBSD，它没有联合缓冲缓存(UBC)，每次写都必须用msync(2)系统调用同步
Variables ¶
var DefaultOptions = &Options{ Timeout: 0, NoGrowSync: false, }
DefaultOptions 默认选项，当nil传入open()的时候用这个默认选项 这里timeout为0，将会无限等待一个文件锁的释放
Functions ¶
This section is empty.
Types ¶
type Bucket ¶
type Bucket struct {
// 这个值不会保存进磁盘，所以必须每个事务都要设置
// 默认情况下页里面装到50%的数据时就会拆分，但是如果你大部分的写都是后面插入（append-only）的话，
// 增加这个值大小非常有用
FillPercent float64
// contains filtered or unexported fields
}
Bucket 代表一个在数据库对键值对集合。
func (*Bucket) CreateBucket ¶
CreateBucket 给定一个键创建一个桶，并返回这个新桶 如果键已经存在，名字是空或者太长，则返回错误 桶实例只在事务的生命周期里面有效
func (*Bucket) CreateBucketIfNotExists ¶
CreateBucketIfNotExists 给定一个键创建一个桶，并返回这个新桶,如果桶已经存在，则返回该桶 如果名字是空或者太长，则返回错误 桶实例只在事务的生命周期里面有效
func (*Bucket) DeleteBucket ¶
DeleteBucket 删除给定的键对应的桶 如果桶不存在或者给定的键对应的不是个桶，就返回错误
func (*Bucket) ForEach ¶
ForEach 给桶里面的所有键值执行一个函数fn 如果函数fn返回错误，则循环结束，并返回这个错误给调用者 在函数fn里面不要修改这个桶，否则会导致未定义的行为
func (*Bucket) NextSequence ¶
NextSequence 为这个桶返回下个自增的值
type BucketStats ¶
type BucketStats struct {
// Page count statistics.
BranchPageN int // number of logical branch pages
BranchOverflowN int // number of physical branch overflow pages
LeafPageN int // number of logical leaf pages
LeafOverflowN int // number of physical leaf overflow pages
// Tree statistics.
KeyN int // number of keys/value pairs
Depth int // number of levels in B+tree
// Page size utilization.
BranchAlloc int // bytes allocated for physical branch pages
BranchInuse int // bytes actually used for branch data
LeafAlloc int // bytes allocated for physical leaf pages
LeafInuse int // bytes actually used for leaf data
// Bucket statistics
BucketN int // total number of buckets including the top bucket
InlineBucketN int // total number on inlined buckets
InlineBucketInuse int // bytes used for inlined buckets (also accounted for in LeafInuse)
}
BucketStats records statistics about resources used by a bucket. (统计相关不翻译了)
func (*BucketStats) Add ¶
func (s *BucketStats) Add(other BucketStats)
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
Cursor （游标）用来有序的遍历一个桶里面所有的key/value， 游标看到桶类型的页时返回的value是nil 游标从一个事务中获得，而且只在这个事务中有效 同理游标返回的key/value也是只在当前事务中有效 改变游标返回的key/value可能会使游标无效 并返回不符合期望的key/value。在改变数据之后，你必须重置你的游标
type DB ¶
type DB struct {
// 如果启用，数据库会在每次提交的时候调用Check()
// 如果数据库处于不一致状态就会报panic
// 因为这个标志有很大性能影响，所以应该只用在调试的时候
StrictMode bool
// 设置NoSync标志将导致数据库在每次提交时跳过fsync()
// 这对于批量加载数据进数据库非常有用，这样你可以重启这个批量加载，即使发生了系统错误或数据库损害
// 尽可能正常使用时不要设置这个标志位
//
// 如果包全局常量IgnoreNoSync是true，则这个值被忽略
// 详情可以看看这个常量到注释
//
// 这个不安全，请谨慎使用
NoSync bool
// 当这个为true时，当扩张数据库时，跳过调用truncate
// 当这个为true时，只在non-ext3/ext4 系统安全
// 跳过truncate可以避免预分配硬盘空间和绕过在重新映射时truncate()和fsync()这两个系统调用
//
// https://github.com/boltdb/bolt/issues/284
NoGrowSync bool
// MmapFlags设置内存映射时的标志位
// 如果你想读取数据库快点，并且你的linux版本是2.6.23+，
// 请设置syscall.MAP_POPULATE，开启文件预读（sequential read-ahead）
MmapFlags int
// MaxBatchSize 是一个batch的最大容量
// 默认值是DefaultMaxBatchSize
// 如果小于等于0，则batch功能不可用
// 不要在调用Batch的时候改这个值
MaxBatchSize int
// MaxBatchDelay 是开始一个batch之前的等待时间
// 默认值是DefaultMaxBatchDelay
// 如果小于等于0，则batch功能不可用
// 不要在调用Batch的时候改这个值
MaxBatchDelay time.Duration
// 当数据库需要创建新当页时，AllocSize 是每次数据库扩张的时候加的量
// 当扩张数据文件时，这样做是用来分摊调用truncate()和fsync()成本
AllocSize int
// contains filtered or unexported fields
}
DB 表示一个桶集合，并把桶持久化到文件里面 所有数据访问都是通过事务，而这个事务又可以从DB里面获得 如果访问之前没有打开Open()，则DB里面的所有函数都会返回ErrDatabaseNotOpen
func (*DB) Batch ¶
Batch 调用一个函数fn，它的行为类似Update 除了：
1. 并发调用Batch，会合并到一个事务执行
2. 传给Batch的函数有可能被执行多次，无论这个函数报错没报错
这意味着Batch执行的函数必须是幂等的，而且在执行成功后数据才能持久化和被调用者看到
最大批大小和延迟时间可以通过这两个配置修改，DB.MaxBatchSize，DB.MaxBatchDelay
Batch 只有在多协程调用它时，有用
func (*DB) Begin ¶
Begin 开始一个新的事务 多个只读事务可以并发使用，但是一次只能有一个写事务 多个写事务会造成阻塞直到当前写事务完成为止
事务不应该依赖另外一个。如果一个协程里面有一个读事务和写事务，有可能会造成写事务死锁， 因为数据库会周期性变大然后重新映射，如果这时候有个读事务打开的时候，写事务就有可能死锁了
如果一个长时间运行的读事务，你可能需要设置DB.InitialMmapSize为一个足够大的值 这样就可以避免潜在的来自写事务的阻塞
重要：你在使用完之后必须关闭只读事务，否则数据库没办法重复利用那些旧的页
type Options ¶
type Options struct {
// Timeout 是等文件锁的时间，如果设置为0，则会无限等下去。
// 这个选项只有在Dawin和Linux下有效
Timeout time.Duration
// 在内存映射文件之前设置DB.NoGrowSync
NoGrowSync bool
// 以只读打开数据库。用flock(..., LOCK_SH |LOCK_NB)来获取一个共享锁
ReadOnly bool
// 在内存映射之前设置DB.MmapFlags
MmapFlags int
// InitialMmapSize 数据库的初始映射大小
// 如果这个大小足够大，则读事务不会阻塞写事务（详情可以看DB.Begin）
//
// 如果小于等于0，则初始映射大小为0
// 如果小于数据库文件大小，则它没有任何作用了
InitialMmapSize int
}
Options 代表打开数据库是可设置的选项
type Stats ¶
type Stats struct {
// Freelist stats
FreePageN int // total number of free pages on the freelist
PendingPageN int // total number of pending pages on the freelist
FreeAlloc int // total bytes allocated in free pages
FreelistInuse int // total bytes used by the freelist
// Transaction stats
TxN int // total number of started read transactions
OpenTxN int // number of currently open read transactions
TxStats TxStats // global, ongoing stats.
}
Stats 数据库的统计数据
type Tx ¶
type Tx struct {
// 这个标志是专门给写相关方法用的，例如WriteTo()
// 设置这个标志，事务就用指定的标志位（syscall.O_DIRECT）来打开数据库文件来拷贝数据
//
// 默认这个标志是不设值的，因为没有这个标志已经满足大部分情况了
// 但是如果数据库文件很大，大过可用内存的时候，要读出整个数据库的话，
// 设置这个标志，那就可以利用syscall.O_DIRECT来避免损坏页高速缓存
WriteFlag int
// contains filtered or unexported fields
}
Tx 表示一个在数据库里的只读或者读写事务 只读事务只用来通过键获取值和创建游标 读写事务用来创建和删除桶，还有创建和删除键
重要：如果你用完了事务，你必须提交或回滚事务 否则页不能被回收，那就不能被读写事务去申请 一个长时间的读事务可能造成数据库大小很快的变大
func (*Tx) Check ¶
Check 为这个事务在数据库上执行一堆一致性检查 如果找到不一致的，就返回一个错误
It can be safely run concurrently on a writable transaction. However, this incurs a high cost for large databases and databases with a lot of subbuckets because of caching. This overhead can be removed if running on a read-only transaction, however, it is not safe to execute other writer transactions at the same time.
func (*Tx) CreateBucket ¶
CreateBucket 创建一个新桶 如果一个桶存在，桶名为空或者太长，就返回错误 桶实例只在当前事务有效
func (*Tx) CreateBucketIfNotExists ¶
CreateBucketIfNotExists 如果桶不存在就创建一个新桶 如果桶名为空或者太长，就返回错误 桶实例只在当前事务有效
func (*Tx) DeleteBucket ¶
DeleteBucket 删除一个桶 如果桶不存在或者根据桶名搜索这个桶时返回的不是一个桶该返回的值时报错
type TxStats ¶
type TxStats struct {
// Page statistics.
PageCount int // number of page allocations
PageAlloc int // total bytes allocated
// Cursor statistics.
CursorCount int // number of cursors created
// Node statistics
NodeCount int // number of node allocations
NodeDeref int // number of node dereferences
// Rebalance statistics.
Rebalance int // number of node rebalances
RebalanceTime time.Duration // total time spent rebalancing
// Split/Spill statistics.
Split int // number of nodes split
Spill int // number of nodes spilled
SpillTime time.Duration // total time spent spilling
// Write statistics.
Write int // number of writes performed
WriteTime time.Duration // total time spent writing to disk
}
TxStats 代表这个事务执行的动作的统计数据
Source Files