diskstack

Documentation

Overview

Package diskstack implements a LIFO queue (known as a stack) on local disk. The stack resizes a single file automatically according to the amount of entries required.

Usage:

s, err := New("/path/to/file", int(0))
if err != nil {
  // Do something.
}

for i := 0; i < 10; i++ {
  if err := s.Push(i); err != nil {
    // Do something.
  }
}

var n int
ok, err := s.Pop(&n)
if err != nil {
  // Do something
}
if !ok {
  // Would mean the queue is empty, its not.
}

fmt.Println(n) // Prints 9

s.Pop(&n)
fmt.Println(n) // Prints 8

fmt.Println("stack length: ", s.Len()) // Prints "stack length: 8"

fmt.Println("stack size in bytes: ", s.Size())

Index

• type Option
  • func NoFlush() Option
• type Stack
  • func New(p string, dataType interface{}, options ...Option) (*Stack, error)
  • func (d *Stack) Close() error
  • func (d *Stack) Len() int
  • func (d *Stack) Pop(data interface{}) (ok bool, err error)
  • func (d *Stack) Push(data interface{}) error
  • func (d *Stack) Size() int
• type VersionInfo

Types

type Option

type Option func(s *Stack)

Option provides an optional argument to New().

func NoFlush

func NoFlush() Option

NoFlush indicates to not flush every write to disk. This increases speed but at the cost of possibly losing a Push() or Pop().

type Stack

type Stack struct {
	// contains filtered or unexported fields
}

Stack implements a LIFO queue that can store a single object type that can be encoded by the gob encoder (encoding/gob) on local disk. The file is constantly resized based for each pop() and push() operation. All operations are thread-safe.

func New

func New(p string, dataType interface{}, options ...Option) (*Stack, error)

New creates a new instance of Stack. p is the location of where to write the stack. The file must not exist. dataType is the value that you will store in the stack. It must be gob encodable. Also see Pop() for more information on what can go here.

func (*Stack) Close

func (d *Stack) Close() error

Close closes the file backing the stack on disk. This does not erase the file.

func (*Stack) Len

func (d *Stack) Len() int

Len returns the amount of items currently on the stack.

func (*Stack) Pop

func (d *Stack) Pop(data interface{}) (ok bool, err error)

Pop returns the last stored value that was on the stack and puts it in data. data must be a pointer type (even to reference types) and must either be the same type as was passed via New() or a pointer to that type. If ok == false and err == nil, it indicates the stack was empty. Note: This should work with almost all fixed types and other basic types. But I'm sure some ***type thing will break this. Pointer to fixed value, struct, and reference types is all that is supported.

func (*Stack) Push

func (d *Stack) Push(data interface{}) error

Push pushes an new entry onto the stack. data must be of the same type passed in New().

func (*Stack) Size

func (d *Stack) Size() int

Size returns the current size of the stack in bytes on disk.

type VersionInfo

type VersionInfo struct {
	// Version is the version of encoding used to by stack to encode this.
	// This is not the same as the Semantic Version of the code.
	Version uint64
	// Created is when the file was actually created.
	Created int64
}

VersionInfo is used to encode version information for the disk stack into our files. This struct can never have a field removed only added.