Directory.h

/*
 * Copyright (c) 2008-2014, Pedigree Developers
 *
 * Please see the CONTRIB file in the root of the source tree for a full
 * list of contributors.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
#ifndef DIRECTORY_H
#define DIRECTORY_H
#include "pedigree/kernel/Log.h"
#include "pedigree/kernel/compiler.h"
#include "pedigree/kernel/process/ConditionVariable.h"
#include "pedigree/kernel/process/Mutex.h"
 
#include <config.h>
#if THREADS && !defined(STANDALONE_MUTEXES)
#include "pedigree/kernel/process/TerminationDeferral.h"
#endif
#include "pedigree/kernel/processor/types.h"
#include "pedigree/kernel/time/Time.h"
#include "pedigree/kernel/utilities/HashTable.h"
#include "pedigree/kernel/utilities/LazyEvaluate.h"
#include "pedigree/kernel/utilities/Pointers.h"
#include "pedigree/kernel/utilities/String.h"
#include "pedigree/kernel/utilities/StringView.h"
#include "pedigree/kernel/utilities/Vector.h"
#include "pedigree/kernel/utilities/utility.h"
 
#include "File.h"
 
class EXPORTED_PUBLIC Directory : public File {
  friend class Filesystem;
 
 public:
  enum class LookupStatus { Found, NotFound, IoError, Retry };
 
  enum class ReadStatus { Complete, Stopped, IoError };
 
  enum class AddStatus { Added, Exists, IoError, Detached };
 
  enum class EntryType : uint8_t {
    Unknown,
    Regular,
    Directory,
    Symlink,
    Fifo,
    Socket,
    CharacterDevice,
    BlockDevice
  };
 
  struct DirectoryEntryView {
    StringView name;
    uintptr_t inode;
    EntryType type;
    uint64_t currentCookie;
    uint64_t nextCookie;
  };
 
  using DirectoryEntryEmitter = bool (*)(void*, const DirectoryEntryView&);
 
  class EXPORTED_PUBLIC ChildLease {
   public:
    ChildLease();
    ~ChildLease();
 
    File* get() const {
      return m_pFile;
    }
 
    explicit operator bool() const {
      return m_pFile != nullptr;
    }
 
    void reset();
 
    // Transfers the tracked-file reference, leaving the stack's deferral local.
    File* releaseOwnership();
 
    void swap(ChildLease& other);
 
   private:
    friend class Directory;
    friend class Filesystem;
    friend class Symlink;
 
    ChildLease(const ChildLease&) = delete;
    ChildLease& operator=(const ChildLease&) = delete;
    ChildLease(ChildLease&&) = delete;
    ChildLease& operator=(ChildLease&&) = delete;
 
    void adopt(File* file);
 
    File* m_pFile;
#if THREADS && !defined(STANDALONE_MUTEXES)
    // A lease's deferral follows its lexical lifetime. Dynamically arming an
    // older object would cross any newer guard's strict LIFO scope.
    TerminationDeferral m_TerminationDeferral;
#endif
  };
 
  class EXPORTED_PUBLIC NameReservation {
   public:
    NameReservation();
    ~NameReservation();
 
    explicit operator bool() const {
      return m_pDirectory != nullptr;
    }
 
    void complete(LookupStatus result);
 
   private:
    friend class Directory;
    friend class Filesystem;
 
    NameReservation(const NameReservation&) = delete;
    NameReservation& operator=(const NameReservation&) = delete;
    NameReservation(NameReservation&&) = delete;
    NameReservation& operator=(NameReservation&&) = delete;
 
    Directory* m_pDirectory;
    String m_Name;
    void* m_pToken;
    bool m_OwnsNamespaceLock;
#if THREADS && !defined(STANDALONE_MUTEXES)
    TerminationDeferral m_TerminationDeferral;
#endif
  };
 
  static Directory* fromFile(File* pF) {
    if (!pF->isDirectory())
      FATAL("Casting non-directory File to Directory!");
    return reinterpret_cast<Directory*>(pF);
  }
 
  Directory();
 
 private:
  Directory(const Directory& file);
  Directory& operator=(const Directory&);
 
 public:
  Directory(const String& name, Time::Timestamp accessedTime, Time::Timestamp modifiedTime,
            Time::Timestamp creationTime, uintptr_t inode, class Filesystem* pFs, size_t size,
            File* pParent);
  virtual ~Directory();
 
  virtual bool isDirectory() {
    return true;
  }
 
  File* getChild(size_t n);
 
  bool isDetached() const {
    return __atomic_load_n(&m_Detached, __ATOMIC_ACQUIRE);
  }
 
  size_t getNumChildren();
 
  ReadStatus enumerate(uint64_t& cookie, DirectoryEntryEmitter emitter, void* context);
 
  ReadStatus isEmpty(bool& empty);
 
  virtual void cacheDirectoryContents();
 
  virtual bool isCachePopulated() const;
 
  File* lookup(const HashedStringView& s) const;
 
  MUST_USE_RESULT bool lookupRetained(const HashedStringView& s, ChildLease& child) const;
 
  MUST_USE_RESULT LookupStatus lookupChild(const HashedStringView& s, ChildLease& child) const;
 
  MUST_USE_RESULT LookupStatus lookupChildAt(uint64_t cookie, const HashedStringView& name,
                                             ChildLease& child) const;
 
  void remove(const HashedStringView& s);
 
  Directory* getReparsePoint() const;
 
  void setReparsePoint(Directory* pTarget);
 
  AddStatus addEphemeralFile(File* pFile);
 
  void removeEphemeralFiles();
 
  bool empty();
 
  void emptyCache();
 
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
  enum class RetainedLookupPhase { BeforeLookup, AfterRetain };
  using RetainedLookupHook = void (*)(Directory*, File*, RetainedLookupPhase);
  static void setRetainedLookupHookForHostedTest(RetainedLookupHook hook);
  const void* cacheLockAddressForHostedTest() const {
    return static_cast<const void*>(&m_CacheLock);
  }
  bool tryCacheLockForHostedTest() const;
#endif
#if HOSTED
  size_t inFlightUsersForHostedTest(const HashedStringView& name) const;
#endif
 
 protected:
  struct DirectoryEntryMetadata {
    DirectoryEntryMetadata();
    DirectoryEntryMetadata(DirectoryEntryMetadata&& other) noexcept;
 
    ~DirectoryEntryMetadata();
 
    // No copy construction (UniqueArray)
    NOT_COPYABLE_OR_ASSIGNABLE(DirectoryEntryMetadata);
 
    // These two should always be known at metadata creation time.
    Directory* pDirectory;
    String filename;
 
    // Space for anything else to be stored by the filesystem.
    UniqueArray<char> opaque;
  };
 
  virtual LookupStatus resolveChild(const StringView& name, File*& child);
 
  virtual bool cacheResolvedChildren() const {
    return true;
  }
 
  virtual LookupStatus resolveChildAt(uint64_t cookie, const StringView& name, File*& child);
 
  virtual ReadStatus readDirectory(uint64_t& cookie, DirectoryEntryEmitter emitter, void* context);
 
 private:
  static File* evaluateEntry(const DirectoryEntryMetadata& meta);
  static void destroyEntry(File* file);
 
  virtual bool isBytewise() const {
    // This will cause read()/write() to fail as readBytewise/writeBytewise
    // are not overridden and remain as their default implementation, which
    // errors out.
    return true;
  }
 
 protected:
  typedef LazyEvaluate<File, DirectoryEntryMetadata, evaluateEntry, destroyEntry> DirectoryEntry;
 
 private:
  typedef HashTable<String, DirectoryEntry*, HashedStringView> DirectoryEntryCache;
  typedef HashTable<String, uint64_t, HashedStringView> DirectoryEntryGenerationCache;
  typedef HashTable<String, bool, HashedStringView> EphemeralEntryCache;
 
  struct InFlightLookup {
    InFlightLookup();
 
    ConditionVariable changed;
    size_t users;
    LookupStatus result;
    bool complete;
    bool invalidated;
  };
 
  typedef HashTable<String, InFlightLookup*, HashedStringView> InFlightLookupCache;
 
  DirectoryEntryCache m_Cache;
 
  DirectoryEntryCache m_ResidentEntries;
 
  Vector<String> m_ResidentOrder;
 
  EphemeralEntryCache m_EphemeralEntries;
 
  DirectoryEntryGenerationCache m_CacheGenerations;
  uint64_t m_NextCacheGeneration;
 
  mutable InFlightLookupCache m_InFlightLookups;
 
  bool m_bCachePopulated;
 
  bool m_Detached;
 
  Directory* m_ReparseTarget = nullptr;
 
  uintptr_t m_ParentInode;
 
  mutable Mutex m_CacheLock;
 
  mutable Mutex m_NamespaceMutationLock;
 
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
  static RetainedLookupHook m_RetainedLookupHook;
#endif
 
 protected:
  virtual const DirectoryEntryCache& getCache() {
    return m_Cache;
  }
 
  void markCachePopulated();
 
  bool addDirectoryEntry(const String& name, File* pTarget);
 
  bool addDirectoryEntry(const String& name, DirectoryEntryMetadata&& meta);
 
  bool reserveDirectoryEntry(const HashedStringView& name, NameReservation& reservation);
 
  bool addCachedDirectoryEntry(NameReservation& reservation, File* pTarget);
 
  void invalidateDirectoryEntry(const HashedStringView& name);
 
  bool removeDirectoryEntry(const HashedStringView& name, File* expected);
 
  Mutex& namespaceMutationLock() {
    return m_NamespaceMutationLock;
  }
 
  void markDetached();
 
  void preallocateDirectoryEntries(size_t count);
 
  virtual File* convertToFile(const DirectoryEntryMetadata& meta);
 
 private:
  bool reserveRenameEntry(const String& name, NameReservation& reservation);
  void moveReservedEntry(NameReservation& sourceReservation, Directory* destination,
                         NameReservation& destinationReservation, File* source);
  // Keep cookies non-negative when exposed through POSIX's signed off_t.
  static constexpr uint64_t ResidentCookie = static_cast<uint64_t>(1) << 62;
 
  uint64_t nextCacheGeneration();
  bool removeEphemeralFileLocked(const HashedStringView& name, File* expected);
  void finishNameReservation(NameReservation& reservation, LookupStatus result);
  bool addResidentDirectoryEntry(NameReservation& reservation, File* pTarget, bool ephemeral);
  bool addResidentDirectoryEntry(NameReservation& reservation, DirectoryEntry* entry,
                                 bool ephemeral, File* createdTarget = nullptr);
  void tombstoneResidentLocked(const HashedStringView& name);
  File* cachedFileLocked(const HashedStringView& name) const;
  static EntryType entryType(File* file);
  LookupStatus lookupChildInternal(const HashedStringView& name, uint64_t cookie, bool hasCookie,
                                   ChildLease& child) const;
  struct EnumerationContext;
  static bool emitBackingEntry(void* context, const DirectoryEntryView& entry);
};
 
extern template class HashTable<String, Directory::DirectoryEntry*, HashedStringView>;
 
#endif