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