vfsobj.cxh

/// @brief VFS object definitions
/// @addtogroup fs_vfs
/// @{
#include <cx/thread/atomic.h>
#include <cx/thread/rwlock.h>
 
struct VFSDir;
 
/// Directory cache accounting. See vfsSetCacheLimits().
typedef struct VFSDirCache {
    atomic(int64) lastprune;   ///< clockTimer() when the last prune ran
    atomic(uint32) dircount;   ///< VFSDir nodes currently in the tree
    uint32 maxdirs;            ///< node count above which a prune is allowed to run
    int64 ttl;                 ///< how long an unused directory survives, in microseconds
} VFSDirCache;
 
/// VFS Object
class VFS {
    VFSDir *root;           ///< Root for namespaceless paths
 
    // Namespaces are never case sensitive even if the paths are
    [noinit] hashtable namespaces;          ///< Hashtable of string/VFSDir
    string curdir;                          ///< Current working directory of the VFS
 
    // Two locks, and vfsdlock is always the outer one: a thread may take vfsdlock and then
    // vfslock, never the reverse.
    //
    // vfslock guards additions to the directory cache and the curdir string. vfsdlock guards
    // operations that destroy VFSDir entries or remove mounts. The invariant that makes that
    // split work is stronger than it looks and is not enforced anywhere: every reader that
    // walks the directory tree takes vfsdlock for read first, so holding vfsdlock for write is
    // by itself exclusive against all of them. That is why the mount and unmount paths mutate
    // the subdirs and files hashtables with vfslock never taken at all. A new code path that
    // takes only vfslock and then touches the tree breaks this.
    RWLock vfslock;
    RWLock vfsdlock;
 
    /// Bumped whenever a mount is added or removed. A lookup that dropped the locks to call a
    /// provider compares this before caching what it learned, so it never records a result for
    /// a directory tree that changed underneath it.
    uint32 mountgen;
    uint32 flags;
    VFSDirCache dcache;   ///< directory cache size accounting
 
    /// Creates a new empty VFS instance with no mounted providers
    ///
    /// The returned VFS contains no data sources. Use vfsMountFS() or
    /// vfsMountProvider() to attach filesystem providers before accessing files.
    ///
    /// @param flags Combination of VFS configuration flags (VFS_ReadOnly, VFS_CaseSensitive, etc.)
    /// @return New VFS instance (never NULL, call objRelease() when done)
    ///
    /// Example:
    /// @code
    ///   VFS *vfs = vfsCreate(0);
    ///   vfsMountFS(vfs, _SL("/"), _SL("c:/data"));
    ///   // ... use VFS ...
    ///   objRelease(&vfs);
    /// @endcode
    factory create(uint32 flags);
 
    // hmm this is a comment
    /// Creates a VFS pre-configured with OS filesystem access
    ///
    /// Returns a VFS that mirrors the underlying OS filesystem. The exact
    /// namespace configuration is platform-dependent:
    ///   - Windows: Each drive letter (c:, d:, etc.) is a separate namespace
    ///   - Unix: Single root namespace at /
    ///
    /// The VFS case sensitivity is configured to match the OS default:
    ///   - Windows: Case-insensitive
    ///   - Unix: Case-sensitive
    ///
    /// This is a convenience function equivalent to creating an empty VFS
    /// and mounting the OS filesystem at the appropriate paths.
    ///
    /// @return VFS instance mirroring OS filesystem, or NULL on failure
    ///
    /// Example:
    /// @code
    ///   VFS *vfs = vfsCreateFromFS();
    ///   if (vfs) {
    ///       // VFS paths now map directly to OS filesystem
    ///       VFSFile *f = vfsOpen(vfs, _SL("c:/data/file.txt"), FS_Read);
    ///   }
    /// @endcode
    [canfail] factory createFromFS();
}
 
class VFSMount {
    object[ObjInst] provider;
    uint32 flags;
 
    factory create(ObjInst *provider, uint32 flags);
}
 
/// @}