1    :  // Copyright 2014 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    :  #ifndef SYZYGY_KASKO_UPLOAD_THREAD_H_
  16    :  #define SYZYGY_KASKO_UPLOAD_THREAD_H_
  17    :  
  18    :  #include <memory>
  19    :  
  20    :  #include "base/callback.h"
  21    :  #include "base/macros.h"
  22    :  #include "base/threading/simple_thread.h"
  23    :  #include "base/win/scoped_handle.h"
  24    :  
  25  m :  namespace base {
  26  m :  class FilePath;
  27  m :  }  // namespace base
  28    :  
  29  m :  namespace kasko {
  30    :  
  31  m :  class WaitableTimer;
  32    :  
  33    :  // Establishes a background thread that uploads crash reports. Each instance has
  34    :  // a configured "exclusive path". Although multiple instances of this class may
  35    :  // have the same exclusive path simultaneously in one or more processes, only
  36    :  // one will be active (and perform uploads) at any time. Any other instances
  37    :  // will wait in the background until the active instance is terminated by
  38    :  // invoking Stop() or via process termination. At that time, one of the waiting
  39    :  // instances will become the active instance.
  40  m :  class UploadThread {
  41  m :   public:
  42    :    // Creates an UploadThread instance. Returns NULL if an error prevents
  43    :    // instantiation.
  44    :    // @param exclusive_path The path for which exclusive access is sought.
  45    :    // @param waitable_timer A timer implementation that defines the interval
  46    :    //     between upload operations. At least one interval will pass before the
  47    :    //     first upload and between any two consecutive uploads.
  48    :    // @param uploader A callback that will be invoked periodically to upload
  49    :    //     crash reports, if any.
  50    :    // @returns an UploadThread instance if successful.
  51  m :    static std::unique_ptr<UploadThread> Create(
  52  m :        const base::FilePath& exclusive_path,
  53  m :        std::unique_ptr<WaitableTimer> waitable_timer,
  54  m :        const base::Closure& uploader);
  55    :  
  56  m :    ~UploadThread();
  57    :  
  58    :    // Starts the background uploading process. If another instance is currently
  59    :    // active with the same exclusive path the new background process simply waits
  60    :    // until it becomes active.
  61    :    // After calling Start() you _must_ call Join() before destroying the
  62    :    // UploadThread.
  63  m :    void Start();
  64    :  
  65    :    // Signals the background uploading process to stop. Returns immediately. You
  66    :    // must call Join() to wait for the background process to terminate.
  67  m :    void Stop();
  68    :  
  69    :    // Signals the background uploading process to stop. Blocks until the current
  70    :    // invocation of the uploader terminates (if any) and the background process
  71    :    // has completely shut down.
  72  m :    void Join();
  73    :  
  74    :    // Immediately initiates a single upload attempt. The attempt will be serviced
  75    :    // by the active UploadThread instance, whether this one or another (possibly
  76    :    // in a separate process). This method returns immediately without waiting for
  77    :    // the upload attempt to complete.
  78    :    //
  79    :    // The upload attempt is guaranteed to take place, regardless of any
  80    :    // subsequent calls to UploadThread::Stop(), as long as this instance has
  81    :    // previously been started via UploadThread::Start.
  82    :    //
  83    :    // If an upload attempt is already active, the requested upload attempt will
  84    :    // take place imediately after its completion. If a previously requested
  85    :    // upload attempt has not yet started, this method has no effect.
  86  m :    void UploadOneNowAsync();
  87    :  
  88  m :   private:
  89  m :    class ThreadImpl : public base::SimpleThread {
  90  m :     public:
  91  m :      explicit ThreadImpl(UploadThread* owner);
  92  m :      ~ThreadImpl() override;
  93    :  
  94    :      // base::SimpleThread implementation.
  95  m :      void Run() override;
  96    :  
  97  m :     private:
  98  m :      UploadThread* owner_;
  99    :  
 100  m :      DISALLOW_COPY_AND_ASSIGN(ThreadImpl);
 101  m :    };
 102    :  
 103  m :    UploadThread(base::win::ScopedHandle mutex,
 104  m :                 base::win::ScopedHandle stop_event,
 105  m :                 base::win::ScopedHandle wake_event,
 106  m :                 std::unique_ptr<WaitableTimer> waitable_timer,
 107  m :                 const base::Closure& uploader);
 108    :  
 109  m :    base::win::ScopedHandle mutex_;
 110  m :    base::win::ScopedHandle stop_event_;
 111  m :    base::win::ScopedHandle wake_event_;
 112  m :    std::unique_ptr<WaitableTimer> waitable_timer_;
 113  m :    base::Closure uploader_;
 114  m :    ThreadImpl thread_impl_;
 115    :  
 116  m :    DISALLOW_COPY_AND_ASSIGN(UploadThread);
 117  m :  };
 118    :  
 119  m :  }  // namespace kasko
 120    :  
 121    :  #endif  // SYZYGY_KASKO_UPLOAD_THREAD_H_