Documentation
¶
Index ¶
- Variables
- func Chmod(rt *Root, pth string, mode os.FileMode) error
- func FlushPath(ctx context.Context, rt *Root, pth string) (ipld.Node, error)
- func IsDir(fsn FSNode) bool
- func IsFile(fsn FSNode) bool
- func Mkdir(r *Root, pth string, opts MkdirOpts) error
- func Mv(r *Root, src, dst string) error
- func PutNode(r *Root, path string, nd ipld.Node) error
- func Touch(rt *Root, pth string, ts time.Time) error
- type Directory
- func (d *Directory) AddChild(name string, nd ipld.Node) error
- func (d *Directory) Child(name string) (FSNode, error)
- func (d *Directory) Flush() error
- func (d *Directory) ForEachEntry(ctx context.Context, f func(NodeListing) error) error
- func (d *Directory) GetCidBuilder() cid.Builder
- func (d *Directory) GetNode() (ipld.Node, error)
- func (d *Directory) List(ctx context.Context) ([]NodeListing, error)
- func (d *Directory) ListNames(ctx context.Context) ([]string, error)
- func (d *Directory) Mkdir(name string) (*Directory, error)
- func (d *Directory) MkdirWithOpts(name string, opts MkdirOpts) (*Directory, error)
- func (d *Directory) Path() string
- func (d *Directory) SetCidBuilder(b cid.Builder)
- func (d *Directory) SetModTime(ts time.Time) error
- func (d *Directory) SetMode(mode os.FileMode) error
- func (d *Directory) Type() NodeType
- func (d *Directory) Uncache(name string)
- func (d *Directory) Unlink(name string) error
- type FSNode
- type File
- func (fi *File) Flush() error
- func (fi *File) GetNode() (ipld.Node, error)
- func (fi *File) ModTime() (time.Time, error)
- func (fi *File) Mode() (os.FileMode, error)
- func (fi *File) Open(flags Flags) (_ FileDescriptor, _retErr error)
- func (fi *File) SetModTime(ts time.Time) error
- func (fi *File) SetMode(mode os.FileMode) error
- func (fi *File) Size() (int64, error)
- func (fi *File) Sync() error
- func (fi *File) Type() NodeType
- type FileDescriptor
- type Flags
- type MkdirOpts
- type NodeListing
- type NodeType
- type PubFunc
- type Republisher
- type Root
- type RootOption
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotYetImplemented = errors.New("not yet implemented") ErrInvalidChild = errors.New("invalid child node") ErrDirExists = errors.New("directory already has entry by that name") )
var ( ErrNotExist = errors.New("no such rootfs") ErrClosed = errors.New("file closed") )
TODO: Remove if not used.
var ErrIsDirectory = errors.New("error: is a directory")
TODO: Remove if not used.
Functions ¶
func Mkdir ¶
Mkdir creates a directory at 'path' under the directory 'd', creating intermediary directories as needed if 'mkparents' is set to true
func Mv ¶
Mv moves the file or directory at 'src' to 'dst' TODO: Document what the strings 'src' and 'dst' represent.
func PutNode ¶
PutNode inserts 'nd' at 'path' in the given mfs TODO: Rename or clearly document that this is not about nodes but actually MFS files/directories (that in the underlying representation can be considered as just nodes). TODO: Document why are we handling IPLD nodes in the first place when we are actually referring to files/directories (that is, it can't be any node, it has to have a specific format). TODO: Can this function add directories or just files? What would be the difference between adding a directory with this method and creating it with `Mkdir`.
Types ¶
type Directory ¶
type Directory struct {
// contains filtered or unexported fields
}
TODO: There's too much functionality associated with this structure, let's organize it (and if possible extract part of it elsewhere) and document the main features of `Directory` here.
func NewDirectory ¶
func NewDirectory(ctx context.Context, name string, node ipld.Node, parent parent, dserv ipld.DAGService, prov provider.MultihashProvider) (*Directory, error)
NewDirectory constructs a new MFS directory.
You probably don't want to call this directly. Instead, construct a new root using NewRoot.
func NewEmptyDirectory ¶ added in v0.30.0
func NewEmptyDirectory(ctx context.Context, name string, parent parent, dserv ipld.DAGService, prov provider.MultihashProvider, opts MkdirOpts) (*Directory, error)
NewEmptyDirectory creates an empty MFS directory with the given options. The directory is added to the DAGService. To create a new MFS root use NewEmptyRootFolder instead.
func (*Directory) AddChild ¶
AddChild adds the node 'nd' under this directory giving it the name 'name'
func (*Directory) ForEachEntry ¶
func (*Directory) GetCidBuilder ¶
GetCidBuilder gets the CID builder of the root node
func (*Directory) MkdirWithOpts ¶ added in v0.23.0
func (*Directory) SetCidBuilder ¶
SetCidBuilder sets the CID builder
type FSNode ¶
type FSNode interface {
GetNode() (ipld.Node, error)
Flush() error
Type() NodeType
SetModTime(ts time.Time) error
SetMode(mode os.FileMode) error
}
FSNode abstracts the `Directory` and `File` structures, it represents any child node in the MFS (i.e., all the nodes besides the `Root`). It is the counterpart of the `parent` interface which represents any parent node in the MFS (`Root` and `Directory`). (Not to be confused with the `unixfs.FSNode`.)
type File ¶
type File struct {
RawLeaves bool
// contains filtered or unexported fields
}
File represents a file in the MFS, its logic its mainly targeted to coordinating (potentially many) `FileDescriptor`s pointing to it.
func NewFile ¶
func NewFile(name string, node ipld.Node, parent parent, dserv ipld.DAGService, providing provider.MultihashProvider) (*File, error)
NewFile returns a NewFile object with the given parameters. If the CID version is non-zero RawLeaves will be enabled. A nil providing parameter means that MFS will not provide content to the routing system.
func (*File) Flush ¶
TODO: Tight coupling with the `FileDescriptor`, at the very least this should be an independent function that takes a `File` argument and automates the open/flush/close operations.
TODO: Why do we need to flush a file that isn't opened? (the `OpenWriteOnly` seems to implicitly be targeting a closed file, a file we forgot to flush? can we close a file without flushing?)
func (*File) GetNode ¶
GetNode returns the dag node associated with this file
TODO: Use this method and do not access the `nodeLock` directly anywhere else.
func (*File) SetModTime ¶ added in v0.23.0
SetModTime sets the files' last modification time.
func (*File) Size ¶
Size returns the size of this file
TODO: Should we be providing this API?
TODO: There's already a `FileDescriptor.Size()` that through the `DagModifier`'s `fileSize` function is doing pretty much the same thing as here, we should at least call that function and wrap the `ErrNotUnixfs` with an MFS text.
type FileDescriptor ¶
type FileDescriptor interface {
io.Reader
CtxReadFull(context.Context, []byte) (int, error)
io.Writer
io.WriterAt
io.Closer
io.Seeker
Truncate(int64) error
Size() (int64, error)
Flush() error
}
One `File` can have many `FileDescriptor`s associated to it (only one if it's RW, many if they are RO, see `File.desclock`). A `FileDescriptor` contains the "view" of the file (through an instance of a `DagModifier`), that's why it (and not the `File`) has the responsibility to `Flush` (which crystallizes that view in the `File`'s `Node`).
type MkdirOpts ¶
type MkdirOpts struct {
Mkparents bool
Flush bool
CidBuilder cid.Builder
Mode os.FileMode
ModTime time.Time
MaxLinks int
MaxHAMTFanout int
HAMTShardingSize int
SizeEstimationMode *uio.SizeEstimationMode
Chunker chunker.SplitterGen // chunker factory for files created in this directory
}
MkdirOpts is used by Mkdir
type PubFunc ¶
PubFunc is the user-defined function that determines exactly what logic entails "publishing" a `Cid` value.
type Republisher ¶
type Republisher struct {
// contains filtered or unexported fields
}
Republisher manages when to publish a given entry.
func NewRepublisher ¶
NewRepublisher creates a new Republisher object to republish the given root using the given short and long time intervals.
func (*Republisher) Close ¶
func (rp *Republisher) Close() error
Close tells the republisher to stop and waits for it to stop.
func (*Republisher) Update ¶
func (rp *Republisher) Update(c cid.Cid)
Update the current value. The value will be published after a delay but each consecutive call to Update may extend this delay up to TimeoutLong.
type Root ¶
type Root struct {
// contains filtered or unexported fields
}
Root represents the root of a filesystem tree.
func NewEmptyRoot ¶ added in v0.30.0
func NewEmptyRoot(ctx context.Context, ds ipld.DAGService, pf PubFunc, prov provider.MultihashProvider, mkdirOpts MkdirOpts, rootOpts ...RootOption) (*Root, error)
NewEmptyRoot creates an empty Root directory with the given directory options. A republisher is created if PubFunc is not nil.
func NewRoot ¶
func NewRoot(ctx context.Context, ds ipld.DAGService, node *dag.ProtoNode, pf PubFunc, prov provider.MultihashProvider, opts ...RootOption) (*Root, error)
NewRoot creates a new Root and starts up a republisher routine for it.
func (*Root) Flush ¶
Flush signals that an update has occurred since the last publish, and updates the Root republisher. TODO: We are definitely abusing the "flush" terminology here.
func (*Root) FlushMemFree ¶
FlushMemFree flushes the root directory and then uncaches all of its links. This has the effect of clearing out potentially stale references and allows them to be garbage collected. CAUTION: Take care not to ever call this while holding a reference to any child directories. Those directories will be bad references and using them may have unintended racy side effects. A better implemented mfs system (one that does smarter internal caching and refcounting) shouldnt need this method. TODO: Review the motivation behind this method once the cache system is refactored.
func (*Root) GetChunker ¶ added in v0.37.0
func (kr *Root) GetChunker() chunker.SplitterGen
GetChunker returns the chunker factory, or nil if using default.
func (*Root) GetDirectory ¶
GetDirectory returns the root directory.
type RootOption ¶ added in v0.37.0
type RootOption func(*Root)
RootOption is a functional option for configuring a Root.
func WithChunker ¶ added in v0.37.0
func WithChunker(c chunker.SplitterGen) RootOption
WithChunker sets the chunker factory for files created in this MFS. If not set (or nil), chunker.DefaultSplitter is used.
func WithHAMTShardingSize ¶ added in v0.37.0
func WithHAMTShardingSize(size int) RootOption
WithHAMTShardingSize sets the per-directory size threshold for switching to HAMT. When a directory's estimated size exceeds this threshold, it converts to HAMT. If not set (0), the global uio.HAMTShardingSize is used.
func WithMaxHAMTFanout ¶ added in v0.37.0
func WithMaxHAMTFanout(n int) RootOption
WithMaxHAMTFanout sets the max fanout (width) for HAMT directories in this MFS. This controls the maximum number of children per HAMT bucket. Must be a power of 2 and multiple of 8.
func WithMaxLinks ¶ added in v0.37.0
func WithMaxLinks(n int) RootOption
WithMaxLinks sets the max links for directories created in this MFS. This is used to determine when to switch between BasicDirectory and HAMTDirectory.
func WithSizeEstimationMode ¶ added in v0.37.0
func WithSizeEstimationMode(mode uio.SizeEstimationMode) RootOption
WithSizeEstimationMode sets the size estimation mode for directories in this MFS. This controls how directory size is estimated for HAMT sharding decisions.
Source Files