mirror of
https://github.com/mindoc-org/mindoc.git
synced 2026-02-27 17:03:57 +08:00
87 lines
3.1 KiB
Go
87 lines
3.1 KiB
Go
// Copyright 2014 The kv Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
/*
|
|
|
|
Package kv implements a simple and easy to use persistent key/value (KV) store.
|
|
|
|
Changelog
|
|
|
|
2016-07-11: KV now uses the stable version of lldb. (github.com/cznic/lldb).
|
|
|
|
The stored KV pairs are sorted in the key collation order defined by an user
|
|
supplied 'compare' function (passed as a field in Options).
|
|
|
|
Keys and Values Limits
|
|
|
|
Keys, as well as the values associated with them, are opaque []bytes. Maximum
|
|
size of a "native" key or value is 65787 bytes. Larger keys or values have to
|
|
be composed of the "native" ones in client code.
|
|
|
|
Database limits
|
|
|
|
The maximum DB size kv can handle is 2^60 bytes (1 exabyte). See also [4]:
|
|
"Block handles".
|
|
|
|
ACID and transactional properties
|
|
|
|
Transactions are resource limited. All changes made by a transaction are held
|
|
in memory until the top level transaction is committed. ACID[1] implementation
|
|
notes/details follows.
|
|
|
|
Atomicity
|
|
|
|
A successfully committed transaction appears (by its effects on the database)
|
|
to be indivisible ("atomic") iff the transaction is performed in isolation. An
|
|
aborted (via RollBack) transaction appears like it never happened under the
|
|
same limitation.
|
|
|
|
Atomic updates to the DB, via functions like Set, Inc, etc., are performed in
|
|
their own automatic transaction. If the partial progress of any such function
|
|
fails at any point, the automatic transaction is canceled via Rollback before
|
|
returning from the function. A non nil error is returned in that case.
|
|
|
|
Consistency
|
|
|
|
All reads, including those made from any other concurrent non isolated
|
|
transaction(s), performed during a not yet committed transaction, are dirty
|
|
reads, i.e. the data returned are consistent with the in-progress state of the
|
|
open transaction, or all of the open transactions. Obviously, conflicts, data
|
|
races and inconsistent states can happen, but iff non isolated transactions are
|
|
performed.
|
|
|
|
Performing a Rollback at a nested transaction level properly returns the
|
|
transaction state (and data read from the DB) to what it was before the
|
|
respective BeginTransaction.
|
|
|
|
Isolation
|
|
|
|
Transactions of the atomic updating functions (Set, Put, Delete ...) are always
|
|
isolated. Transactions controlled by BeginTransaction/Commit/RollBack, are
|
|
isolated iff their execution is serialized.
|
|
|
|
Durability
|
|
|
|
Transactions are committed using the two phase commit protocol(2PC)[2] and a
|
|
write ahead log(WAL)[3]. DB recovery after a crash is performed automatically
|
|
using data from the WAL. Last transaction data, either of an in progress
|
|
transaction or a transaction being committed at the moment of the crash, can get
|
|
lost.
|
|
|
|
No protection from non readable files, files corrupted by other processes or by
|
|
memory faults or other HW problems, is provided. Always properly backup your DB
|
|
data file(s).
|
|
|
|
Links
|
|
|
|
Referenced from above:
|
|
|
|
[1]: http://en.wikipedia.org/wiki/ACID
|
|
[2]: http://en.wikipedia.org/wiki/2PC
|
|
[3]: http://en.wikipedia.org/wiki/Write_ahead_logging
|
|
[4]: http://godoc.org/github.com/cznic/lldb#Allocator
|
|
|
|
*/
|
|
package kv
|