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: %d", s.Size())

Index

• Variables
• type Option
  • func MaxDepth(d int) Option
  • func NoFlush() Option
  • func UseExisting() Option
• type Reverse
  • func (r Reverse) Read(b []byte) (n int, err error)
  • func (r Reverse) Seek(offset int64, whence int) (int64, error)
  • func (r Reverse) Write(p []byte) (n int, err error)
• 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{}) error
  • func (d *Stack) Push(data interface{}) error
  • func (d *Stack) Size() int
• type VersionInfo

Variables

var (
	// StackFull indicates that MaxDepth was reached and no entries can be added
	// until a Pop() occurs.
	StackFull = errors.New("stack has reached its max depth")
	// StackEmpty indicates the stack had no entries.
	StackEmpty = errors.New("stack was empty")
)

Types

type Option

type Option func(s *Stack)

Option provides an optional argument to New().

func MaxDepth

func MaxDepth(d int) Option

MaxDepth indicates how many entries can be in the Stack. If d <= 0, this is limited only by disk space.

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().

func UseExisting

func UseExisting() Option

UseExisting indicates that "p" exists with an existing queue.

type Reverse

type Reverse struct {
	RW io.ReadWriteSeeker
}

reverse is a wrapper around an io.ReadWriter that will assume all data is in the reverse format. See methods for more information. reverse is not thread-safe!

func (Reverse) Read

func (r Reverse) Read(b []byte) (n int, err error)

Read implements io.Reader, but in a unique way. Instead of reading the first byte from the stream into b[0], it will read it into b[len(b)-1], the second into b[len(b)-2], etc ... This implementation costs 2 Seeks + 1 Read + an O(n/2) op.

func (Reverse) Seek

func (r Reverse) Seek(offset int64, whence int) (int64, error)

func (Reverse) Write

func (r Reverse) Write(p []byte) (n int, err error)

Write implements io.Writer, but in a unique way. Instead or writing the first byte of the slice to the stream, it writes p[len(p)-1], then p[len(p)-2] and so on.

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 unless UseExisting() is passed. dataType is the value that you will store in the stack. It must be gob encodable. See Pop() for more information on what can be stored.

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{}) 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. Structs will only have Public fields stored (gob restriction). 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 in Unix time.
	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.