Documentation
¶
Overview ¶
Package file implements a File API over a content-addressable blob.Store.
A File as defined by this package differs from the POSIX file model in that any File may have both binary content and "children". Thus, any File is also a directory, which can contain other files in a Merkle tree structure.
A File is addressed by a storage key, corresponding to the current state of its content, metadata, and children (recursively). File metadata are stored as wire-format protocol buffers, as defined in file/wiretype/wiretype.proto.
Basic usage:
ctx := context.Background() f := file.New(cas, nil) // create a new, empty file f.WriteAt(ctx, data, 0) // write some data to the file key, err := f.Flush(ctx) // commit the file to storage
To open an existing file,
f, err := file.Open(ctx, cas, key)
The I/O methods of a File require a context argument. For compatibility with the standard interfaces in the io package, a File provides a wrapper for a request-scoped context:
_, err := io.Copy(dst, f.Cursor(ctx))
A value of the file.Cursor type should not be used outside the dynamic extent of the request whose context it captures.
Metadata ¶
A File supports a subset of POSIX style data metadata, including mode, modification time, and owner/group identity. These metadata are not interpreted by the API, but will be persisted if they are set.
By default, a File does not persist stat metadata. To enable stat persistence, you may either set the Stat field of file.NewOptions when the File is created, or use the Persist method of the Stat value to enable or disable persistence:
s := f.Stat() s.ModTime = time.Now() s.Update().Persist(true)
The file.Stat type defines the stat attributes that can be persisted.
Synchronization ¶
The exported methods of *File and the views of its data (Child, Data, Stat, XAttr) are safe for concurrent use by multiple goroutines.
Index ¶
- Variables
- func Encode(f *File) *wiretype.Object
- type Child
- type Cursor
- func (c *Cursor) Close() error
- func (c *Cursor) Read(data []byte) (int, error)
- func (c *Cursor) ReadAt(data []byte, offset int64) (int, error)
- func (c *Cursor) Seek(offset int64, whence int) (int64, error)
- func (c *Cursor) Stat() (fs.FileInfo, error)
- func (c *Cursor) Write(data []byte) (int, error)
- func (c *Cursor) WriteAt(data []byte, offset int64) (int, error)
- type Data
- type File
- func (f *File) Child() Child
- func (f *File) Cursor(ctx context.Context) *Cursor
- func (f *File) Data() Data
- func (f *File) Flush(ctx context.Context) (string, error)
- func (f *File) Key() string
- func (f *File) Name() string
- func (f *File) New(opts *NewOptions) *File
- func (f *File) Open(ctx context.Context, name string) (*File, error)
- func (f *File) ReadAt(ctx context.Context, data []byte, offset int64) (int, error)
- func (f *File) Scan(ctx context.Context, visit func(ScanItem) bool) error
- func (f *File) SetData(ctx context.Context, r io.Reader) error
- func (f *File) Stat() Stat
- func (f *File) Truncate(ctx context.Context, offset int64) error
- func (f *File) WriteAt(ctx context.Context, data []byte, offset int64) (int, error)
- func (f *File) XAttr() XAttr
- type FileInfo
- type NewOptions
- type ScanItem
- type Stat
- type XAttr
Constants ¶
This section is empty.
Variables ¶
var ( // ErrChildNotFound indicates that a requested child file does not exist. ErrChildNotFound = errors.New("child file not found") )
Functions ¶
Types ¶
type Child ¶
type Child struct {
// contains filtered or unexported fields
}
Child provides access to the children of a file.
func (Child) Names ¶
Names returns a lexicographically ordered slice of the names of all the children of the file.
func (Child) Release ¶
Release discards all up-to-date cached children of the file. It returns the number of records that were released.
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
A Cursor bundles a *File with a context so that the file can be used with the standard interfaces defined by the io package. A Cursor value may be used only during the lifetime of the request whose context it binds.
Each Cursor maintains a separate offset position on the underlying file, affecting Read, Write, and Seek operations on that cursor. The offset value for a newly-created cursor is always 0.
func (*Cursor) Close ¶
Close implements the io.Closer interface. A File does not have a system descriptor, so "closing" performs a flush but does not invalidate the file.
func (*Cursor) Read ¶
Read reads up to len(data) bytes into data from the current offset, and reports the number of bytes successfully read, as io.Reader.
type Data ¶
type Data struct {
// contains filtered or unexported fields
}
Data is a view of the data associated with a file.
type File ¶
type File struct {
// contains filtered or unexported fields
}
A File represents a writable file stored in a content-addressable blobstore.
func New ¶
func New(s blob.CAS, opts *NewOptions) *File
New constructs a new, empty File with the given options and backed by s. The caller must call the new file's Flush method to ensure it is written to storage. If opts == nil, defaults are chosen.
func (*File) Cursor ¶
Cursor binds f with a context so that it can be used to satisfy the standard interfaces defined by the io package. The resulting cursor may be used only during the lifetime of the request whose context it binds.
func (*File) Flush ¶
Flush flushes the current state of the file to storage if necessary, and returns the resulting storage key. This is the canonical way to obtain the storage key for a file.
func (*File) Key ¶
Key returns the storage key of f if it is known, or "" if the file has not been flushed to storage in its current form.
func (*File) Name ¶
Name reports the attributed name of f, which may be "" if f is not a child file and was not assigned a name at creation.
func (*File) New ¶
func (f *File) New(opts *NewOptions) *File
New constructs a new empty node backed by the same store as f. If f persists stat metadata, then the new file does also.
func (*File) Open ¶
Open opens the specified child file of f, or returns ErrChildNotFound if no such child exists.
func (*File) ReadAt ¶
ReadAt reads up to len(data) bytes into data from the given offset, and reports the number of bytes successfully read, as io.ReaderAt.
func (*File) Scan ¶
Scan recursively visits f and all its descendants in depth-first left-to-right order, calling visit for each file. If visit returns false, no descendants of f are visited.
func (*File) SetData ¶
SetData fully reads r replaces the binary contents of f with its data. On success, any existing data for f are discarded. In case of error, the contents of f are not changed.
func (*File) Stat ¶
Stat returns the current stat metadata for f. Calling this method does not change stat persistence for f, use the Clear and Update methods of the Stat value to do that.
func (*File) Truncate ¶
Truncate modifies the length of f to end at offset, extending or contracting it as necessary.
type FileInfo ¶
type FileInfo struct {
// contains filtered or unexported fields
}
FileInfo implements the fs.FileInfo interface. The underlying data source has concrete type *File.
type NewOptions ¶
type NewOptions struct {
// The name to attribute to the new file. The name of a File is not
// persisted in storage.
Name string
// Initial file metadata to associate with the file. If not nil, the new
// file will persist stat metadata to storage. However, the contents are not
// otherwise interpreted.
Stat *Stat
// The block splitter configuration to use. If omitted, the default values
// from the split package are used. Split configurations are not persisted
// in storage, but descendants created from a file (via the New method) will
// inherit the parent file config if they do not specify their own.
Split *block.SplitConfig
}
NewOptions control the creation of new files.
type ScanItem ¶
type ScanItem struct {
*File // the current file being visited
Parent *File // the parent file (nil at the root)
Name string // the name of File within its parent ("" at the root)
}
A ScanItem is the argument to the Scan callback.
type Stat ¶
type Stat struct {
Mode fs.FileMode `json:"mode,omitempty"`
ModTime time.Time `json:"mod_time,omitempty"`
// Numeric ID and name of file owner.
OwnerID int `json:"owner_id,omitempty"`
OwnerName string `json:"owner_name,omitempty"`
// Numeric ID and name of file group.
GroupID int `json:"group_id,omitempty"`
GroupName string `json:"group_name,omitempty"`
// contains filtered or unexported fields
}
A Stat is a view into the stat metadata for a file. Modifying fields of the Stat value does not affect the underlying file unless the caller explicitly calls Update.
func (Stat) Clear ¶
Clear clears the current stat metadata for the file associated with s. Calling this method does not change whether stat is persisted, nor does it modify the current contents of s, so calling Update on the same s will restore the cleared values. Clear returns s.
func (Stat) Persist ¶
Persist enables (ok == true) or disables (ok == false) stat persistence for the file associated with s. The contents of s are not changed. It returns s.
func (Stat) Persistent ¶
Persistent reports whether the file associated with s persists stat.
type XAttr ¶
type XAttr struct {
// contains filtered or unexported fields
}
XAttr provides access to the extended attributes of a file.
func (XAttr) Clear ¶
func (x XAttr) Clear()
Clear removes all the extended attributes set on the file.
func (XAttr) Get ¶
Get returns the value corresponding to the given key, or "" if the key is not defined.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package root defines a storage representation for pointers to file trees and associated metadata.
|
Package root defines a storage representation for pointers to file trees and associated metadata. |
|
Package wiretype defines the encoding types for the ffs package.
|
Package wiretype defines the encoding types for the ffs package. |