fsm

README

fsm

File Space Management - allocates & frees space on a file!

Example

package main

import (
        "encoding/binary"
        "fmt"
        "os"

        "github.com/roy2220/fsm"
)

func main() {
        const fn = "./test_storage"
        defer os.Remove(fn)

        // store a list of words
        func() {
                fs := new(fsm.FileStorage).Init()

                if err := fs.Open(fn, true); err != nil {
                        panic(err)
                }

                defer fs.Close()
                // set the list head
                fs.SetPrimarySpace(-1)

                for _, word := range []string{"cat", "dog", "fish", "ant", "bird"} {
                        // allocate space for a list item
                        space, buf := fs.AllocateSpace(8 + 1 + len(word))
                        // set the next list item (8 bytes)
                        binary.BigEndian.PutUint64(buf[0:], uint64(fs.PrimarySpace()))
                        // set the word length (1 byte)
                        buf[8] = byte(len(word))
                        // set the word (n byte)
                        copy(buf[9:], word)
                        // update the list head
                        fs.SetPrimarySpace(space)
                }
        }()

        // load the list of words
        func() {
                fs := new(fsm.FileStorage).Init()

                if err := fs.Open(fn, true); err != nil {
                        panic(err)
                }

                defer fs.Close()
                // get the list head
                nextSpace := fs.PrimarySpace()

                for nextSpace >= 0 {
                        space := nextSpace
                        buf := fs.AccessSpace(space)
                        // get the next list item (8 bytes)
                        nextSpace = int64(binary.BigEndian.Uint64(buf[0:]))
                        // get the word length (1 byte)
                        wordLen := int(buf[8])
                        // get the word (n byte)
                        word := string(buf[9 : 9+wordLen])
                        fmt.Println(word)
                        // release the space of the list item
                        // (free space could be reused by the following AllocateSpace calls)
                        //fs.FreeSpace(space)
                }
        }()
}

Documentation

Overview

Package fsm implements file space management.

Example

package main

import (
	"encoding/binary"
	"fmt"
	"os"

	"github.com/roy2220/fsm"
)

func main() {
	const fn = "./test_storage"
	defer os.Remove(fn)

	// store a list of words
	func() {
		fs := new(fsm.FileStorage).Init()

		if err := fs.Open(fn, true); err != nil {
			panic(err)
		}

		defer fs.Close()
		// set the list head
		fs.SetPrimarySpace(-1)

		for _, word := range []string{"cat", "dog", "fish", "ant", "bird"} {
			// allocate space for a list item
			space, buf := fs.AllocateSpace(8 + 1 + len(word))
			// set the next list item (8 bytes)
			binary.BigEndian.PutUint64(buf[0:], uint64(fs.PrimarySpace()))
			// set the word length (1 byte)
			buf[8] = byte(len(word))
			// set the word (n byte)
			copy(buf[9:], word)
			// update the list head
			fs.SetPrimarySpace(space)
		}
	}()

	// load the list of words
	func() {
		fs := new(fsm.FileStorage).Init()

		if err := fs.Open(fn, true); err != nil {
			panic(err)
		}

		defer fs.Close()
		// get the list head
		nextSpace := fs.PrimarySpace()

		for nextSpace >= 0 {
			space := nextSpace
			buf := fs.AccessSpace(space)
			// get the next list item (8 bytes)
			nextSpace = int64(binary.BigEndian.Uint64(buf[0:]))
			// get the word length (1 byte)
			wordLen := int(buf[8])
			// get the word (n byte)
			word := string(buf[9 : 9+wordLen])
			fmt.Println(word)
			// release the space of the list item
			// (free space could be reused by the following AllocateSpace calls)
			//fs.FreeSpace(space)
		}
	}()
}

Output:

bird
ant
fish
dog
cat

Index

• type FileStorage
  • func (fs *FileStorage) AccessAlignedSpace(block int64) []byte
  • func (fs *FileStorage) AccessSpace(space int64) []byte
  • func (fs *FileStorage) AllocateAlignedSpace(blockSize int) (int64, []byte)
  • func (fs *FileStorage) AllocateSpace(spaceSize int) (int64, []byte)
  • func (fs *FileStorage) Close() error
  • func (fs *FileStorage) FreeAlignedSpace(block int64)
  • func (fs *FileStorage) FreeSpace(space int64)
  • func (fs *FileStorage) Init() *FileStorage
  • func (fs *FileStorage) Open(fileName string, createFileIfNotExists bool) error
  • func (fs *FileStorage) PrimarySpace() int64
  • func (fs *FileStorage) SetPrimarySpace(primarySpace int64)
  • func (fs *FileStorage) Stats() Stats
• type Stats

Examples

• Package

Types

type FileStorage

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

FileStorage represents a file storage.

func (*FileStorage) AccessAlignedSpace

func (fs *FileStorage) AccessAlignedSpace(block int64) []byte

AccessAlignedSpace returns an ephemeral accessor of the given aligned space, aka a block, on the file (a byte slice for reading/writing space, may get *INVALIDATED* after calling Allocate.../Free...).

func (*FileStorage) AccessSpace

func (fs *FileStorage) AccessSpace(space int64) []byte

AccessSpace returns an ephemeral accessor of the given space on the file (a byte slice for reading/writing space, may get *INVALIDATED* after calling Allocate.../Free...).

func (*FileStorage) AllocateAlignedSpace

func (fs *FileStorage) AllocateAlignedSpace(blockSize int) (int64, []byte)

AllocateAlignedSpace allocates aligned space, aka a block, with the given size on the file, returns the aligned space allocated and an ephemeral accessor (a byte slice for reading/writing space, may get *INVALIDATED* after calling Allocate.../Free...).

func (*FileStorage) AllocateSpace

func (fs *FileStorage) AllocateSpace(spaceSize int) (int64, []byte)

AllocateSpace allocates space with the given size on the file, returns the space allocated and an ephemeral accessor (a byte slice for reading/writing space, may get *INVALIDATED* after calling Allocate.../Free...).

func (*FileStorage) Close

func (fs *FileStorage) Close() error

Close closes the file storage.

func (*FileStorage) FreeAlignedSpace

func (fs *FileStorage) FreeAlignedSpace(block int64)

FreeAlignedSpace releases the given aligned space, aka a block, back to the file.

func (*FileStorage) FreeSpace

func (fs *FileStorage) FreeSpace(space int64)

FreeSpace releases the given space back to the file.

func (*FileStorage) Init

func (fs *FileStorage) Init() *FileStorage

Init initializes the file storage and returns it.

func (*FileStorage) Open

func (fs *FileStorage) Open(fileName string, createFileIfNotExists bool) error

Open opens a file storage on the given file.

func (*FileStorage) PrimarySpace

func (fs *FileStorage) PrimarySpace() int64

PrimarySpace returns the primary space on the file. The primary space is allocated by user and serves for user-defined metadata.

func (*FileStorage) SetPrimarySpace

func (fs *FileStorage) SetPrimarySpace(primarySpace int64)

SetPrimarySpace set the primary space on the file. The primary space is allocated by user and serves for user-defined metadata.

func (*FileStorage) Stats

func (fs *FileStorage) Stats() Stats

Stats returns the stats of the file.

type Stats

type Stats struct {
	SpaceSize                 int
	UsedSpaceSize             int
	MappedSpaceSize           int
	AllocatedSpaceSize        int
	BlockAllocationBitmapSize int
	DismissedSpaceSize        int
}

Stats represents the stats about file space management.