README
¶
JSON Persistence
Allows for using a single variable as shared state or config, with fairly transparent optional persistence to a file.
Documentation
¶
Overview ¶
Package jpersist - Persist as JSON to disk
Index ¶
Constants ¶
const DefaultFilePermissions = os.FileMode(0640)
DefaultFilePermissions is used when creating files.
Variables ¶
var ErrNoFile = errors.New("no file configured")
ErrNoFile indicates a read or write was attempted without a file configured.
Functions ¶
This section is empty.
Types ¶
type CannotMarshalError ¶
type CannotMarshalError error
CannotMarshalError is a decorator returned by NewManager to indicate that the Managered type cannot be marshalled to JSON.
type Config ¶
type Config struct {
// File is the name of the file written when
File string
// FilePermissions is used when creating a new file. If unset,
// DefaultFilePermissions will be used.
FilePermissions os.FileMode
// WriteDelay adds a delay between a call to Manager.Unlock and
// writing to file to allow for other modifications. This prevents a
// burst of modifications from causing a burst of disk activity.
WriteDelay time.Duration
// OnError is called in its own goroutine when Unlock or UnlockAndWrite
// return an error, if not nil. The passed in error will be an
// UnlockError.
OnError func(err error)
}
Config configures a manager.
type Manager ¶
type Manager[T any] struct { C *T /* Originally C for Config, but also C for Ctate. */ // contains filtered or unexported fields }
Manager handles locking and persistence for a variable of type T, which will never be nil.
func NewManager ¶
NewManager returns a new Manager which wraps a variable of type T, ready for use. The config is optional. If the config is non-nil and config.File names a non-empty file, the file's contents will be unmarshalled into the returned Manager's C. The returned Manager will keep a copy of config, if not nil.
func (*Manager[T]) Lock ¶
func (m *Manager[T]) Lock()
Lock acquires an exclusive lock on m. This should be called before making changes to m.C. Call Unlock or UnlockAndWrite to release the lock.
func (*Manager[T]) RLock ¶
func (m *Manager[T]) RLock()
RLock acquires a shared lock on m. No changes should be made to m.C. Call RUnlock to release the lock.
func (*Manager[T]) RUnlock ¶
func (m *Manager[T]) RUnlock()
RUnlock releases a lock acquired by RLock. Do not call RUnlock without calling RLock first.
func (*Manager[T]) Reload ¶
Reload closes and reopens m's file and reloads its contents into m.C. If m wasn't configured with a file, Reload returns ErrNoFile.
func (*Manager[T]) Unlock ¶
Unlock releases a lock acquired by Lock(). If m.C has changed, it will be written to the file if one is configured, possibly after a configured delay. If an error is returned, it will also be passed to the callback configured when m was created, if one was configured. If the write is delayed, the error will only be passed to the callback, not returned. Do not call Unlock without calling Lock first.
func (*Manager[T]) UnlockAndWrite ¶
UnlockAndWrite is like Unlock, but does not wait before writing m.C to the configured file. This is useful for reducing the risk of changes to m.C being lost should the program crash before writing. Do not call UnlockAndWrite without calling Lock first.
type UnlockError ¶
type UnlockError struct {
// CallerFile and CallerLine point to the caller of the function which
// would have returned this error. If the file and line weren't
// available, they will be their respective zero values.
CallerFile string
CallerLine int
// Err is this error's underlying error.
Err error
}
UnlockError is returned from Unlock and UnlockAndWrite and passed to Config.OnError to indicate something went wrong while unlocking.
func (UnlockError) Error ¶
func (err UnlockError) Error() string
Error satisties the error interface.
Source Files