update WriteTo() docs

This commit updates and revises some of the documentation around
Tx.WriteTo() and how O_DIRECT is no longer the default.

3 files changed, 13 insertions, 15 deletions

diff --git a/README.md b/README.md
index 32759ce..80353ab 100644
--- a/README.md
+++ b/README.md
@@ -426,8 +426,11 @@ func (*Bucket) DeleteBucket(key []byte) error
 Bolt is a single file so it's easy to backup. You can use the `Tx.WriteTo()`
 function to write a consistent view of the database to a writer. If you call
 this from a read-only transaction, it will perform a hot backup and not block
-your other database reads and writes. It will also use `O_DIRECT` when available
-to prevent page cache trashing.
+your other database reads and writes.
+
+By default, it will use a regular file handle which will utilize the operating
+system's page cache. See the [`Tx`](https://godoc.org/github.com/boltdb/bolt#Tx)
+documentation for information about optimizing for larger-than-RAM datasets. 
 
 One common use case is to backup over HTTP so you can use tools like `cURL` to
 do database backups:
diff --git a/boltsync_unix.go b/boltsync_unix.go
index 8db8977..f504425 100644
--- a/boltsync_unix.go
+++ b/boltsync_unix.go
@@ -2,8 +2,6 @@
 
 package bolt
 
-var odirect int
-
 // fdatasync flushes written data to a file descriptor.
 func fdatasync(db *DB) error {
 	return db.file.Sync()
diff --git a/tx.go b/tx.go
index e181aab..3273106 100644
--- a/tx.go
+++ b/tx.go
@@ -30,14 +30,12 @@ type Tx struct {
 	stats          TxStats
 	commitHandlers []func()
 
-	// WriteFlag specifies the flag for write related methods
-	// like WriteTo.
-	// Tx opens the database file with the specified
-	// flag to copy the data.
+	// WriteFlag specifies the flag for write-related methods like WriteTo().
+	// Tx opens the database file with the specified flag to copy the data.
 	//
-	// By default, the flag is set to empty for in-memory workload.
-	// To avoid cache trashing for large on disk workload, set this
-	// flag with o_direct.
+	// By default, the flag is unset, which works well for mostly in-memory
+	// workloads. For databases that are much larger than available RAM,
+	// set the flag to syscall.O_DIRECT to avoid trashing the page cache.
 	WriteFlag int
 }
 
@@ -283,17 +281,17 @@ func (tx *Tx) Copy(w io.Writer) error {
 // If err == nil then exactly tx.Size() bytes will be written into the writer.
 func (tx *Tx) WriteTo(w io.Writer) (n int64, err error) {
 	// Attempt to open reader with WriteFlag
-	var f *os.File
-	if f, err = os.OpenFile(tx.db.path, os.O_RDONLY|tx.WriteFlag, 0); err != nil {
+	f, err := os.OpenFile(tx.db.path, os.O_RDONLY|tx.WriteFlag, 0)
+	if err != nil {
 		return 0, err
 	}
+	defer f.Close()
 
 	// Copy the meta pages.
 	tx.db.metalock.Lock()
 	n, err = io.CopyN(w, f, int64(tx.db.pageSize*2))
 	tx.db.metalock.Unlock()
 	if err != nil {
-		_ = f.Close()
 		return n, fmt.Errorf("meta copy: %s", err)
 	}
 
@@ -301,7 +299,6 @@ func (tx *Tx) WriteTo(w io.Writer) (n int64, err error) {
 	wn, err := io.CopyN(w, f, tx.Size()-int64(tx.db.pageSize*2))
 	n += wn
 	if err != nil {
-		_ = f.Close()
 		return n, err
 	}