1    :  // Copyright 2013 Google Inc. All Rights Reserved.
   2    :  //
   3    :  // Licensed under the Apache License, Version 2.0 (the "License");
   4    :  // you may not use this file except in compliance with the License.
   5    :  // You may obtain a copy of the License at
   6    :  //
   7    :  //     http://www.apache.org/licenses/LICENSE-2.0
   8    :  //
   9    :  // Unless required by applicable law or agreed to in writing, software
  10    :  // distributed under the License is distributed on an "AS IS" BASIS,
  11    :  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    :  // See the License for the specific language governing permissions and
  13    :  // limitations under the License.
  14    :  //
  15    :  // This file declares the TraceFileWriter class, which encapsulates
  16    :  // functionality for writing buffers of data to a trace file. This uses raw
  17    :  // unbuffered writing to disk, and as such only writes multiples of the disk
  18    :  // sector size.
  19    :  //
  20    :  // Intended use:
  21    :  //
  22    :  //   TraceFileWriter w;
  23    :  //   if (!w.Open(path))
  24    :  //     ...
  25    :  //
  26    :  //   // Use w.block_size() to make sure we are getting data with the appropriate
  27    :  //   // block size.
  28    :  //
  29    :  //   if (!w.WriteHeader(process_info))
  30    :  //     ...
  31    :  //   while (...) {
  32    :  //     if (!w.WriteRecord(buffer, length))
  33    :  //       ...
  34    :  //   }
  35    :  //
  36    :  //   if (!w.Close())
  37    :  //     ...
  38    :  
  39    :  #ifndef SYZYGY_TRACE_SERVICE_TRACE_FILE_WRITER_H_
  40    :  #define SYZYGY_TRACE_SERVICE_TRACE_FILE_WRITER_H_
  41    :  
  42    :  #include "base/files/file_path.h"
  43    :  #include "base/win/scoped_handle.h"
  44    :  #include "syzygy/trace/service/process_info.h"
  45    :  
  46    :  namespace trace {
  47    :  namespace service {
  48    :  
  49    :  // A trace file writer encapsulates the bare minimum functionality necessary for
  50    :  // writing a trace file. It is not thread-safe.
  51    :  class TraceFileWriter {
  52    :   public:
  53    :    // Constructor.
  54    :    TraceFileWriter();
  55    :  
  56    :    // Destructor.
  57    :    ~TraceFileWriter();
  58    :  
  59    :    // Given information about a process, generates a suggested base filename for
  60    :    // a trace.
  61    :    // @param process_info Information about the process for which we are creating
  62    :    //     a trace file.
  63    :    // @returns A suggested basename for the trace file.
  64    :    static base::FilePath GenerateTraceFileBaseName(
  65    :        const ProcessInfo& process_info);
  66    :  
  67    :    // Opens a trace file at the given path.
  68    :    // @param path The path of the trace file to write.
  69    :    // @returns true on success, false otherwise.
  70    :    bool Open(const base::FilePath& path);
  71    :  
  72    :    // Writes the header to the trace file. A trace file is associated with a
  73    :    // single running process, so we require a populated process-info struct.
  74    :    // @param process_info Information about the process to which this trace file
  75    :    //     pertains.
  76    :    // @returns true on success, false otherwise.
  77    :    bool WriteHeader(const ProcessInfo& process_info);
  78    :  
  79    :    // Writes a record of data to disk.
  80    :    // @param data The record to be written. This must contain a RecordPrefix.
  81    :    //     This currently only supports records that contain a
  82    :    //     TraceFileSegmenHeader.
  83    :    // @param length The maximum length of continuous data that may be
  84    :    //     contained in the record. The actual length is stored in the header, but
  85    :    //     this is necessary to ensure that the header is valid.
  86    :    // @returns true on success, false otherwise.
  87    :    bool WriteRecord(const void* data, size_t length);
  88    :  
  89    :    // Closes the trace file.
  90    :    // @returns true on success, false otherwise.
  91    :    // @note If this is not called manually the trace-file will close itself when
  92    :    //     the writer goes out of scope.
  93    :    bool Close();
  94    :  
  95    :    // @returns the path to the trace file.
  96    :    // @note This is only valid after Open has returned successfully.
  97  E :    base::FilePath path() const { return path_; }
  98    :  
  99    :    // @returns the block size.
 100    :    // @note This is only valid after Open has returned successfully.
 101  E :    size_t block_size() const { return block_size_; }
 102    :  
 103    :   protected:
 104    :    // The path to the trace file being written.
 105    :    base::FilePath path_;
 106    :  
 107    :    // The handle to the file that's being written to.
 108    :    base::win::ScopedHandle handle_;
 109    :  
 110    :    // The block size being used by the trace file writer.
 111    :    size_t block_size_;
 112    :  
 113    :   private:
 114    :    DISALLOW_COPY_AND_ASSIGN(TraceFileWriter);
 115    :  };
 116    :  
 117    :  }  // namespace service
 118    :  }  // namespace trace
 119    :  
 120    :  #endif  // SYZYGY_TRACE_SERVICE_TRACE_FILE_WRITER_H_