Line data    Source code

       1             : /* Copyright (C) 2021 Wildfire Games.
       2             :  *
       3             :  * Permission is hereby granted, free of charge, to any person obtaining
       4             :  * a copy of this software and associated documentation files (the
       5             :  * "Software"), to deal in the Software without restriction, including
       6             :  * without limitation the rights to use, copy, modify, merge, publish,
       7             :  * distribute, sublicense, and/or sell copies of the Software, and to
       8             :  * permit persons to whom the Software is furnished to do so, subject to
       9             :  * the following conditions:
      10             :  *
      11             :  * The above copyright notice and this permission notice shall be included
      12             :  * in all copies or substantial portions of the Software.
      13             :  *
      14             :  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
      15             :  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
      16             :  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
      17             :  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
      18             :  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
      19             :  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
      20             :  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
      21             :  */
      22             : 
      23             : /*
      24             :  * IO event recording
      25             :  */
      26             : 
      27             : // traces are useful for determining the optimal ordering of archived files
      28             : // and can also serve as a repeatable IO benchmark.
      29             : 
      30             : // note: since FileContents are smart pointers, the trace can't easily
      31             : // be notified when they are released (relevant for cache simulation).
      32             : // we have to assume that users process one file at a time -- as they
      33             : // should.
      34             : 
      35             : #ifndef INCLUDED_TRACE
      36             : #define INCLUDED_TRACE
      37             : 
      38             : #include "lib/os_path.h"
      39             : 
      40             : // stores information about an IO event.
      41           5 : class TraceEntry
      42             : {
      43             : public:
      44             :     enum EAction
      45             :     {
      46             :         Load = 'L',
      47             :         Store = 'S'
      48             :     };
      49             : 
      50             :     TraceEntry(EAction action, const Path& pathname, size_t size);
      51             :     TraceEntry(const std::wstring& text);
      52             : 
      53           4 :     EAction Action() const
      54             :     {
      55           4 :         return m_action;
      56             :     }
      57             : 
      58           5 :     const Path& Pathname() const
      59             :     {
      60           5 :         return m_pathname;
      61             :     }
      62             : 
      63           4 :     size_t Size() const
      64             :     {
      65           4 :         return m_size;
      66             :     }
      67             : 
      68             :     std::wstring EncodeAsText() const;
      69             : 
      70             : private:
      71             :     // note: keep an eye on the class size because all instances are kept
      72             :     // in memory (see ITrace)
      73             : 
      74             :     // time (as returned by timer_Time) after the operation completes.
      75             :     // rationale: when loading, the VFS doesn't know file size until
      76             :     // querying the cache or retrieving file information.
      77             :     float m_timestamp;
      78             : 
      79             :     EAction m_action;
      80             : 
      81             :     Path m_pathname;
      82             : 
      83             :     // size of file.
      84             :     // rationale: other applications using this trace format might not
      85             :     // have access to the VFS and its file information.
      86             :     size_t m_size;
      87             : };
      88             : 
      89             : 
      90             : // note: to avoid interfering with measurements, this trace container
      91             : // does not cause any IOs (except of course in Load/Store)
      92          83 : struct ITrace
      93             : {
      94             :     virtual ~ITrace();
      95             : 
      96             :     virtual void NotifyLoad(const Path& pathname, size_t size) = 0;
      97             :     virtual void NotifyStore(const Path& pathname, size_t size) = 0;
      98             : 
      99             :     /**
     100             :      * store all entries into a file.
     101             :      *
     102             :      * @param pathname (native, absolute)
     103             :      *
     104             :      * note: the file format is text-based to allow human inspection and
     105             :      * because storing filename strings in a binary format would be a
     106             :      * bit awkward.
     107             :      **/
     108             :     virtual Status Store(const OsPath& pathname) const = 0;
     109             : 
     110             :     /**
     111             :      * load entries from file.
     112             :      *
     113             :      * @param pathname (native, absolute)
     114             :      *
     115             :      * replaces any existing entries.
     116             :      **/
     117             :     virtual Status Load(const OsPath& pathname) = 0;
     118             : 
     119             :     virtual const TraceEntry* Entries() const = 0;
     120             :     virtual size_t NumEntries() const = 0;
     121             : };
     122             : 
     123             : typedef std::shared_ptr<ITrace> PITrace;
     124             : 
     125             : extern PITrace CreateDummyTrace(size_t maxSize);
     126             : extern PITrace CreateTrace(size_t maxSize);
     127             : 
     128             : #endif  // #ifndef INCLUDED_TRACE