README
¶
txfile
Documentation
¶
Index ¶
- type File
- type Options
- type Page
- func (p *Page) Bytes() ([]byte, error)
- func (p *Page) Dirty() bool
- func (p *Page) Flush() error
- func (p *Page) Free() error
- func (p *Page) ID() PageID
- func (p *Page) Load() error
- func (p *Page) MarkDirty() error
- func (p *Page) Readonly() bool
- func (p *Page) SetBytes(contents []byte) error
- func (p *Page) Writable() bool
- type PageID
- type Tx
- func (tx *Tx) Active() bool
- func (tx *Tx) Alloc() (page *Page, err error)
- func (tx *Tx) AllocN(n int) (pages []*Page, err error)
- func (tx *Tx) CheckpointWAL() error
- func (tx *Tx) Close() error
- func (tx *Tx) Commit() error
- func (tx *Tx) Flush() error
- func (tx *Tx) Page(id PageID) (*Page, error)
- func (tx *Tx) PageSize() int
- func (tx *Tx) Readonly() bool
- func (tx *Tx) Rollback() error
- func (tx *Tx) Root() PageID
- func (tx *Tx) RootPage() (*Page, error)
- func (tx *Tx) SetRoot(id PageID)
- func (tx *Tx) Writable() bool
- type TxOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type File ¶
type File struct {
// contains filtered or unexported fields
}
File provides transactional support to pages of a file. A file is split into pages of type PageSize. Pages within the file are only accessible by page IDs from within active transactions.
func Open ¶
Open opens or creates a new transactional file. Open tries to create the file, if the file does not exist yet. Returns an error if file access fails, file can not be locked or file meta pages are found to be invalid.
func (*File) Begin ¶
Begin creates a new read-write transaction. The transaction returned does hold the Reserved Lock on the file. Use Close, Rollback, or Commit to release the lock.
func (*File) BeginReadonly ¶
BeginReadonly creates a new readonly transaction. The transaction returned does hold the Shared Lock on the file. Use Close() to release the lock.
func (*File) BeginWith ¶
BeginWith creates a new readonly or read-write transaction, with additional transaction settings.
func (*File) Close ¶
Close closes the file, after all transactions have been quit. After closing a file, no more transactions can be started.
type Options ¶
type Options struct {
// MaxSize sets the maximum file size in bytes. This should be a multiple of PageSize.
// If it's not a multiple of PageSize, the actual files maximum size is rounded downwards
// to the next multiple of PageSize.
// A value of 0 indicates the file can grow without limits.
MaxSize uint64
// PageSize sets the files page size on file creation. PageSize is ignored if
// the file already exists.
// If PageSize is not configured, the OSes main memory page size is selected.
PageSize uint32
// Prealloc disk space if MaxSize is set.
Prealloc bool
// Open file in readonly mode.
Readonly bool
}
Options provides common file options used when opening or creating a file.
type Page ¶
type Page struct {
// contains filtered or unexported fields
}
Page provides access to an on disk page. Pages can only be overwritten from within a read-write Transaction. Writes are be buffered until transaction commit, such that other but the current transaction will not be able to see file changes.
func (*Page) Bytes ¶
Bytes returns the page its contents. One can only modify the buffer in write transaction, if Load() or SetBytes() have been called before Bytes(). Otherwise a non-recoverable BUS panic might be triggerd (program will be killed by OS). Bytes returns an error if the page has just been allocated (no backing buffer) or the transaction is already been closed. Use SetBytes() or Load(), to initialize the buffer of a newly allocated page.
func (*Page) Dirty ¶
Dirty reports if the page is marked as dirty and needs to be flushed on commit.
func (*Page) Flush ¶
Flush flushes the page write buffer, if the page is marked as dirty. The page its contents must not be changed after calling Flush, as the flush is executed asynchronously in the background. Dirty pages will be automatically flushed on commit.
func (*Page) Free ¶
Free marks a page as free. Freeing a dirty page will return an error. The page will be returned to the allocator when the transaction commits.
func (*Page) ID ¶
ID returns the pages PageID. The ID can be used to store a reference to this page, for use within another transaction.
func (*Page) Load ¶
Load reads the pages original contents into a cached memory buffer, allowing for in-place modifications to the page. Load returns and error, if used from within a readonly transaction. If the page has been allocated from within the current transaction, a new temporary buffer will be allocated. After load, the write-buffer can be accessed via Bytes(). After modifications to the buffer, one must use MarkDirty(), so the page will be flushed on commit.
func (*Page) MarkDirty ¶
MarkDirty marks a page as dirty. MarkDirty should only be used if in-place modification to the pages buffer have been made, after use of Load().
func (*Page) SetBytes ¶
SetBytes sets the new contents of a page. If the size of contents is less then the files page size, the original contents must be read. If the length of contents matches the page size, a reference to the contents buffer will be held. To enforce a copy, use Load(), Bytes(), copy() and MarkDirty().
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx provides access to pages in a File. A transaction MUST always be closed, so to guarantee locks being released as well.
func (*Tx) Active ¶
Active returns true if the transaction can still be used to access pages. A transaction becomes inactive after Close, Commit or Rollback. Errors within a transaction might inactivate the transaction as well. When encountering errors, one should check if the transaction still can be used.
func (*Tx) Alloc ¶
Alloc allocates a new writable page with yet empty contents. Use Load(), Bytes and MarkDirty(), or SetBytes() to fill the page with new contents. Returns an error if the transaction is readonly or no more space is available.
func (*Tx) AllocN ¶
AllocN allocates n potentially non-contious, yet empty pages. Returns an error if the transaction is readonly or no more space is available.
func (*Tx) CheckpointWAL ¶
CheckpointWAL copies all overwrite pages contents into the original pages. Only already committed pages from older transactions will be overwritten. Checkpointing only copies the contents and marks the overwrite pages as freed. The final transaction Commit is required, to propage the WAL mapping changes to all other transactions. Dirty pages are not overwritten. Manual checkpointing should be executed at the end of a transaction, right before committing, so to reduce writes if contents is to be overwritten anyways.
func (*Tx) Close ¶
Close closes the transaction, releasing any locks held by the transaction. It is safe to call Close multiple times. Close on an inactive transaction will be ignored. A non-committed read-write transaction will be rolled back on close. To guaranteed the File and Locking state being valid, even on panic or early return on error, one should also defer the Close operation on new transactions. For example:
tx := f.Begin()
defer tx.Close()
err := some operation
if err != nil {
return err
}
return tx.Commit()
func (*Tx) Commit ¶
Commit commits the current transaction to file. The commit step needs to take the Exclusive Lock, waiting for readonly transactions to be Closed. Returns an error if the transaction has already been closed by Close, Rollback or Commit.
func (*Tx) Page ¶
Page accesses a page by ID. Accessed pages are cached. Retrieving a page that has already been accessed, will return a pointer to the same Page object. Returns an error if the id is known to be invalid or the page has already been freed.
func (*Tx) Readonly ¶
Readonly returns true if no modifications to the page are allowed. Trying to write to a readonly page might result in a non-recoverable panic.
func (*Tx) Rollback ¶
Rollback rolls back and closes the current transaction. Rollback returns an error if the transaction has already been closed by Close, Rollback or Commit.
func (*Tx) Root ¶
Root returns the data root page id. This ID must be set via SetRoot to indicate the start of application data to later transactions. On new files, the default root is 0, as no application data are stored yet.
func (*Tx) RootPage ¶
RootPage returns the application data root page, if the root id has been set in the past. Returns nil, if no root page is set.
type TxOptions ¶
type TxOptions struct {
// Readonly transaction.
Readonly bool
// Allow write transaction to allocate meta pages from overflow area.
// Potentially increasing the file size past the configured max size.
// This setting should only be used to guarantee progress when having a
// transaction only freeing pages.
// Later transactions will try to release pages from the overflow area and
// truncate the file, such that we have a chance to operate within max-size
// limits again.
EnableOverflowArea bool
// MetaAreaGrowPercentage sets the percentage of meta pages in use, until
// the meta-area grows again. The value must be between 0 and 100.
// The default value is 80%.
MetaAreaGrowPercentage int
// Number of pages in wal overwrite log to automatically trigger
// CheckpointWAL on commit.
WALLimit uint
}
TxOptions adds some per transaction options user can set.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
cleanup
Package cleanup provides common helpers for common cleanup patterns on defer Use the helpers with `defer`.
|
Package cleanup provides common helpers for common cleanup patterns on defer Use the helpers with `defer`. |
|
invariant
Package invariant provides helpers for checking and panicing on faulty invariants.
|
Package invariant provides helpers for checking and panicing on faulty invariants. |
|
iter
Package iter provides functions for common array iteration strategies.
|
Package iter provides functions for common array iteration strategies. |
|
Package txfiletest provides utilities for testing on top of txfile.
|
Package txfiletest provides utilities for testing on top of txfile. |