aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorTommi Virtanen <tv@eagain.net>2014-08-24 15:42:55 -0700
committerTommi Virtanen <tv@eagain.net>2015-02-18 12:26:45 -0800
commitadbb1a19c1b93a95f17a4eb3c5524e5be8b0d10f (patch)
tree03bf30a873b68f7820dcb910b87eb639f22786ae /README.md
parentMerge pull request #309 from everdev/operation-go (diff)
downloaddedo-adbb1a19c1b93a95f17a4eb3c5524e5be8b0d10f.tar.gz
dedo-adbb1a19c1b93a95f17a4eb3c5524e5be8b0d10f.tar.xz
Add transaction batching
DB.Batch makes it easy to make lots of small transactions with significantly better performance. Batch combines multiple concurrent Update calls into a single disk transaction, managing errors smartly.
Diffstat (limited to 'README.md')
-rw-r--r--README.md42
1 files changed, 42 insertions, 0 deletions
diff --git a/README.md b/README.md
index cb65702..bfaccfc 100644
--- a/README.md
+++ b/README.md
@@ -125,6 +125,48 @@ no mutating operations are allowed within a read-only transaction. You can only
retrieve buckets, retrieve values, and copy the database within a read-only
transaction.
+
+#### Batch read-write transactions
+
+Each `DB.Update()` waits for disk to commit the writes. This overhead
+can be minimized by combining multiple updates with the `DB.Batch()`
+function:
+
+```go
+err := db.Batch(func(tx *bolt.Tx) error {
+ ...
+ return nil
+})
+```
+
+Concurrent Batch calls are opportunistically combined into larger
+transactions. Batch is only useful when there are multiple goroutines
+calling it.
+
+The trade-off is that `Batch` can call the given
+function multiple times, if parts of the transaction fail. The
+function must be idempotent and side effects must take effect only
+after a successful return from `DB.Batch()`.
+
+For example: don't display messages from inside the function, instead
+set variables in the enclosing scope:
+
+```go
+var id uint64
+err := db.Batch(func(tx *bolt.Tx) error {
+ // Find last key in bucket, decode as bigendian uint64, increment
+ // by one, encode back to []byte, and add new key.
+ ...
+ id = newValue
+ return nil
+})
+if err != nil {
+ return ...
+}
+fmt.Println("Allocated ID %d", id)
+```
+
+
#### Managing transactions manually
The `DB.View()` and `DB.Update()` functions are wrappers around the `DB.Begin()`