xpcom/glue/FileUtils.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_FileUtils_h
   8 #define mozilla_FileUtils_h
   9
  10 #include "nscore.h"  // nullptr
  11
  12 #if defined(XP_UNIX)
  13 #  include <unistd.h>
  14 #elif defined(XP_WIN)
  15 #  include <io.h>
  16 #endif
  17 #include "prio.h"
  18 #include "prlink.h"
  19
  20 #include "mozilla/Scoped.h"
  21 #include "nsIFile.h"
  22 #include <errno.h>
  23 #include <limits.h>
  24
  25 namespace mozilla {
  26
  27 #if defined(XP_WIN)
  28 typedef void* filedesc_t;
  29 typedef const wchar_t* pathstr_t;
  30 #else
  31 typedef int filedesc_t;
  32 typedef const char* pathstr_t;
  33 #endif
  34
  35 /**
  36  * ScopedCloseFD is a RAII wrapper for POSIX file descriptors
  37  *
  38  * Instances |close()| their fds when they go out of scope.
  39  */
  40 struct ScopedCloseFDTraits {
  41   typedef int type;
  42   static type empty() { return -1; }
  43   static void release(type aFd) {
  44     if (aFd != -1) {
  45       close(aFd);
  46     }
  47   }
  48 };
  49 typedef Scoped<ScopedCloseFDTraits> ScopedClose;
  50
  51 #if defined(MOZILLA_INTERNAL_API)
  52
  53 /**
  54  * AutoFDClose is a RAII wrapper for PRFileDesc.
  55  *
  56  * Instances |PR_Close| their fds when they go out of scope.
  57  **/
  58 struct ScopedClosePRFDTraits {
  59   typedef PRFileDesc* type;
  60   static type empty() { return nullptr; }
  61   static void release(type aFd) {
  62     if (aFd) {
  63       PR_Close(aFd);
  64     }
  65   }
  66 };
  67 typedef Scoped<ScopedClosePRFDTraits> AutoFDClose;
  68
  69 /* RAII wrapper for FILE descriptors */
  70 struct ScopedCloseFileTraits {
  71   typedef FILE* type;
  72   static type empty() { return nullptr; }
  73   static void release(type aFile) {
  74     if (aFile) {
  75       fclose(aFile);
  76     }
  77   }
  78 };
  79 typedef Scoped<ScopedCloseFileTraits> ScopedCloseFile;
  80
  81 /**
  82  * Fallocate efficiently and continuously allocates files via fallocate-type
  83  * APIs. This is useful for avoiding fragmentation. On sucess the file be padded
  84  * with zeros to grow to aLength.
  85  *
  86  * @param aFD file descriptor.
  87  * @param aLength length of file to grow to.
  88  * @return true on success.
  89  */
  90 bool fallocate(PRFileDesc* aFD, int64_t aLength);
  91
  92 /**
  93  * Use readahead to preload shared libraries into the file cache before loading.
  94  * WARNING: This function should not be used without a telemetry field trial
  95  *          demonstrating a clear performance improvement!
  96  *
  97  * @param aFile nsIFile representing path to shared library
  98  */
  99 void ReadAheadLib(nsIFile* aFile);
 100
 101 /**
 102  * Use readahead to preload a file into the file cache before reading.
 103  * WARNING: This function should not be used without a telemetry field trial
 104  *          demonstrating a clear performance improvement!
 105  *
 106  * @param aFile nsIFile representing path to shared library
 107  * @param aOffset Offset into the file to begin preloading
 108  * @param aCount Number of bytes to preload (SIZE_MAX implies file size)
 109  * @param aOutFd Pointer to file descriptor. If specified, ReadAheadFile will
 110  *        return its internal, opened file descriptor instead of closing it.
 111  */
 112 void ReadAheadFile(nsIFile* aFile, const size_t aOffset = 0,
 113                    const size_t aCount = SIZE_MAX,
 114                    filedesc_t* aOutFd = nullptr);
 115
 116 /*
 117  * Wrappers for PR_GetLibraryName and PR_GetLibraryFilePathname.
 118  */
 119 PathString GetLibraryName(pathstr_t aDirectory, const char* aLib);
 120 PathString GetLibraryFilePathname(pathstr_t aName, PRFuncPtr aAddr);
 121
 122 #endif  // MOZILLA_INTERNAL_API
 123
 124 /**
 125  * Use readahead to preload shared libraries into the file cache before loading.
 126  * WARNING: This function should not be used without a telemetry field trial
 127  *          demonstrating a clear performance improvement!
 128  *
 129  * @param aFilePath path to shared library
 130  */
 131 void ReadAheadLib(pathstr_t aFilePath);
 132
 133 /**
 134  * Use readahead to preload a file into the file cache before loading.
 135  * WARNING: This function should not be used without a telemetry field trial
 136  *          demonstrating a clear performance improvement!
 137  *
 138  * @param aFilePath path to shared library
 139  * @param aOffset Offset into the file to begin preloading
 140  * @param aCount Number of bytes to preload (SIZE_MAX implies file size)
 141  * @param aOutFd Pointer to file descriptor. If specified, ReadAheadFile will
 142  *        return its internal, opened file descriptor instead of closing it.
 143  */
 144 void ReadAheadFile(pathstr_t aFilePath, const size_t aOffset = 0,
 145                    const size_t aCount = SIZE_MAX,
 146                    filedesc_t* aOutFd = nullptr);
 147
 148 /**
 149  * Use readahead to preload a file into the file cache before reading.
 150  * When this function exits, the file pointer is guaranteed to be in the same
 151  * position it was in before this function was called.
 152  * WARNING: This function should not be used without a telemetry field trial
 153  *          demonstrating a clear performance improvement!
 154  *
 155  * @param aFd file descriptor opened for read access
 156  * (on Windows, file must be opened with FILE_FLAG_SEQUENTIAL_SCAN)
 157  * @param aOffset Offset into the file to begin preloading
 158  * @param aCount Number of bytes to preload (SIZE_MAX implies file size)
 159  */
 160 void ReadAhead(filedesc_t aFd, const size_t aOffset = 0,
 161                const size_t aCount = SIZE_MAX);
 162
 163 }  // namespace mozilla
 164
 165 #endif