Merge pull request #273 from wpedrak/mlock-flag

Add `Mlock` flag.

bolt_unix.go

@@ -51,7 +51,7 @@ func funlock(db *DB) error {
 // mmap memory maps a DB's data file.
 func mmap(db *DB, sz int) error {
 	// Map the data file to memory.
-	b, err := syscall.Mmap(int(db.file.Fd()), 0, sz, syscall.PROT_READ, syscall.MAP_SHARED|db.MmapFlags)
+	b, err := unix.Mmap(int(db.file.Fd()), 0, sz, syscall.PROT_READ, syscall.MAP_SHARED|db.MmapFlags)
 	if err != nil {
 		return err
 	}
@@ -78,7 +78,7 @@ func munmap(db *DB) error {
 	}
 
 	// Unmap using the original byte slice.
-	err := syscall.Munmap(db.dataref)
+	err := unix.Munmap(db.dataref)
 	db.dataref = nil
 	db.data = nil
 	db.datasz = 0

db.go

@@ -120,6 +120,12 @@ type DB struct {
 	// of truncate() and fsync() when growing the data file.
 	AllocSize int
 
+	// Mlock locks database file in memory when set to true.
+	// It prevents major page faults, however used memory can't be reclaimed.
+	//
+	// Supported only on Unix via mlock/munlock syscalls.
+	Mlock bool
+
 	path     string
 	openFile func(string, int, os.FileMode) (*os.File, error)
 	file     *os.File
@@ -188,6 +194,7 @@ func Open(path string, mode os.FileMode, options *Options) (*DB, error) {
 	db.MmapFlags = options.MmapFlags
 	db.NoFreelistSync = options.NoFreelistSync
 	db.FreelistType = options.FreelistType
+	db.Mlock = options.Mlock
 
 	// Set default values for later DB operations.
 	db.MaxBatchSize = DefaultMaxBatchSize
@@ -337,7 +344,8 @@ func (db *DB) mmap(minsz int) error {
 	}
 
 	// Ensure the size is at least the minimum size.
-	var size = int(info.Size())
+	fileSize := int(info.Size())
+	var size = fileSize
 	if size < minsz {
 		size = minsz
 	}
@@ -346,6 +354,13 @@ func (db *DB) mmap(minsz int) error {
 		return err
 	}
 
+	if db.Mlock {
+		// Unlock db memory
+		if err := db.munlock(fileSize); err != nil {
+			return err
+		}
+	}
+
 	// Dereference all mmap references before unmapping.
 	if db.rwtx != nil {
 		db.rwtx.root.dereference()
@@ -361,6 +376,13 @@ func (db *DB) mmap(minsz int) error {
 		return err
 	}
 
+	if db.Mlock {
+		// Don't allow swapping of data file
+		if err := db.mlock(fileSize); err != nil {
+			return err
+		}
+	}
+
 	// Save references to the meta pages.
 	db.meta0 = db.page(0).meta()
 	db.meta1 = db.page(1).meta()
@@ -422,6 +444,30 @@ func (db *DB) mmapSize(size int) (int, error) {
 	return int(sz), nil
 }
 
+func (db *DB) munlock(fileSize int) error {
+	if err := munlock(db, fileSize); err != nil {
+		return fmt.Errorf("munlock error: " + err.Error())
+	}
+	return nil
+}
+
+func (db *DB) mlock(fileSize int) error {
+	if err := mlock(db, fileSize); err != nil {
+		return fmt.Errorf("mlock error: " + err.Error())
+	}
+	return nil
+}
+
+func (db *DB) mrelock(fileSizeFrom, fileSizeTo int) error {
+	if err := db.munlock(fileSizeFrom); err != nil {
+		return err
+	}
+	if err := db.mlock(fileSizeTo); err != nil {
+		return err
+	}
+	return nil
+}
+
 // init creates a new database file and initializes its meta pages.
 func (db *DB) init() error {
 	// Create two meta pages on a buffer.
@@ -462,6 +508,7 @@ func (db *DB) init() error {
 	if err := fdatasync(db); err != nil {
 		return err
 	}
+	db.filesz = len(buf)
 
 	return nil
 }
@@ -973,6 +1020,12 @@ func (db *DB) grow(sz int) error {
 		if err := db.file.Sync(); err != nil {
 			return fmt.Errorf("file sync error: %s", err)
 		}
+		if db.Mlock {
+			// unlock old file and lock new one
+			if err := db.mrelock(db.filesz, sz); err != nil {
+				return fmt.Errorf("mlock/munlock error: %s", err)
+			}
+		}
 	}
 
 	db.filesz = sz
@@ -1064,6 +1117,11 @@ type Options struct {
 	// OpenFile is used to open files. It defaults to os.OpenFile. This option
 	// is useful for writing hermetic tests.
 	OpenFile func(string, int, os.FileMode) (*os.File, error)
+
+	// Mlock locks database file in memory when set to true.
+	// It prevents potential page faults, however
+	// used memory can't be reclaimed. (UNIX only)
+	Mlock bool
 }
 
 // DefaultOptions represent the options used if nil options are passed into Open().

mlock_unix.go

@@ -0,0 +1,36 @@
+// +build !windows
+
+package bbolt
+
+import "golang.org/x/sys/unix"
+
+// mlock locks memory of db file
+func mlock(db *DB, fileSize int) error {
+	sizeToLock := fileSize
+	if sizeToLock > db.datasz {
+		// Can't lock more than mmaped slice
+		sizeToLock = db.datasz
+	}
+	if err := unix.Mlock(db.dataref[:sizeToLock]); err != nil {
+		return err
+	}
+	return nil
+}
+
+//munlock unlocks memory of db file
+func munlock(db *DB, fileSize int) error {
+	if db.dataref == nil {
+		return nil
+	}
+
+	sizeToUnlock := fileSize
+	if sizeToUnlock > db.datasz {
+		// Can't unlock more than mmaped slice
+		sizeToUnlock = db.datasz
+	}
+
+	if err := unix.Munlock(db.dataref[:sizeToUnlock]); err != nil {
+		return err
+	}
+	return nil
+}

mlock_windows.go

@@ -0,0 +1,11 @@
+package bbolt
+
+// mlock locks memory of db file
+func mlock(_ *DB, _ int) error {
+	panic("mlock is supported only on UNIX systems")
+}
+
+//munlock unlocks memory of db file
+func munlock(_ *DB, _ int) error {
+	panic("munlock is supported only on UNIX systems")
+}

unix_test.go

@@ -0,0 +1,116 @@
+// +build !windows
+
+package bbolt_test
+
+import (
+	"fmt"
+	"testing"
+
+	bolt "go.etcd.io/bbolt"
+	"golang.org/x/sys/unix"
+)
+
+func TestMlock_DbOpen(t *testing.T) {
+	// 32KB
+	skipOnMemlockLimitBelow(t, 32*1024)
+
+	db := MustOpenWithOption(&bolt.Options{Mlock: true})
+	defer db.MustClose()
+}
+
+// Test change between "empty" (16KB) and "non-empty" db
+func TestMlock_DbCanGrow_Small(t *testing.T) {
+	// 32KB
+	skipOnMemlockLimitBelow(t, 32*1024)
+
+	db := MustOpenWithOption(&bolt.Options{Mlock: true})
+	defer db.MustClose()
+
+	if err := db.Update(func(tx *bolt.Tx) error {
+		b, err := tx.CreateBucketIfNotExists([]byte("bucket"))
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		key := []byte("key")
+		value := []byte("value")
+		if err := b.Put(key, value); err != nil {
+			t.Fatal(err)
+		}
+
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+}
+
+// Test crossing of 16MB (AllocSize) of db size
+func TestMlock_DbCanGrow_Big(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping test in short mode")
+	}
+
+	// 32MB
+	skipOnMemlockLimitBelow(t, 32*1024*1024)
+
+	chunksBefore := 64
+	chunksAfter := 64
+
+	db := MustOpenWithOption(&bolt.Options{Mlock: true})
+	defer db.MustClose()
+
+	for chunk := 0; chunk < chunksBefore; chunk++ {
+		insertChunk(t, db, chunk)
+	}
+	dbSize := fileSize(db.f)
+
+	for chunk := 0; chunk < chunksAfter; chunk++ {
+		insertChunk(t, db, chunksBefore+chunk)
+	}
+	newDbSize := fileSize(db.f)
+
+	if newDbSize <= dbSize {
+		t.Errorf("db didn't grow: %v <= %v", newDbSize, dbSize)
+	}
+}
+
+func insertChunk(t *testing.T, db *DB, chunkId int) {
+	chunkSize := 1024
+
+	if err := db.Update(func(tx *bolt.Tx) error {
+		b, err := tx.CreateBucketIfNotExists([]byte("bucket"))
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		for i := 0; i < chunkSize; i++ {
+			key := []byte(fmt.Sprintf("key-%d-%d", chunkId, i))
+			value := []byte("value")
+			if err := b.Put(key, value); err != nil {
+				t.Fatal(err)
+			}
+		}
+
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// Main reason for this check is travis limiting mlockable memory to 64KB
+// https://github.com/travis-ci/travis-ci/issues/2462
+func skipOnMemlockLimitBelow(t *testing.T, memlockLimitRequest uint64) {
+	var info unix.Rlimit
+	if err := unix.Getrlimit(unix.RLIMIT_MEMLOCK, &info); err != nil {
+		t.Fatal(err)
+	}
+
+	if info.Cur < memlockLimitRequest {
+		t.Skip(fmt.Sprintf(
+			"skipping as RLIMIT_MEMLOCK is unsufficient: %v < %v",
+			info.Cur,
+			memlockLimitRequest,
+		))
+	}
+}