dom/serviceworkers/ServiceWorkerJob.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_dom_serviceworkerjob_h
   8 #define mozilla_dom_serviceworkerjob_h
   9
  10 #include "nsCOMPtr.h"
  11 #include "nsString.h"
  12 #include "nsTArray.h"
  13
  14 class nsIPrincipal;
  15
  16 namespace mozilla {
  17
  18 class ErrorResult;
  19
  20 namespace dom {
  21
  22 class ServiceWorkerJob {
  23  public:
  24   // Implement this interface to receive notification when a job completes or
  25   // is discarded.
  26   class Callback {
  27    public:
  28     // Called once when the job completes.  If the job is started, then this
  29     // will be called.  If a job is never executed due to browser shutdown,
  30     // then this method will never be called.  This method is always called
  31     // on the main thread asynchronously after Start() completes.
  32     virtual void JobFinished(ServiceWorkerJob* aJob, ErrorResult& aStatus) = 0;
  33
  34     // If the job has not started and will never start, then this will be
  35     // called; either JobFinished or JobDiscarded will be called, but not both.
  36     virtual void JobDiscarded(ErrorResult& aStatus) = 0;
  37
  38     NS_INLINE_DECL_PURE_VIRTUAL_REFCOUNTING
  39   };
  40
  41   enum class Type { Register, Update, Unregister };
  42
  43   enum class State { Initial, Started, Finished };
  44
  45   Type GetType() const;
  46
  47   State GetState() const;
  48
  49   // Determine if the job has been canceled.  This does not change the
  50   // current State, but indicates that the job should progress to Finished
  51   // as soon as possible.
  52   bool Canceled() const;
  53
  54   // Determine if the result callbacks have already been called.  This is
  55   // equivalent to the spec checked to see if the job promise has settled.
  56   bool ResultCallbacksInvoked() const;
  57
  58   bool IsEquivalentTo(ServiceWorkerJob* aJob) const;
  59
  60   // Add a callback that will be invoked when the job's result is available.
  61   // Some job types will invoke this before the job is actually finished.
  62   // If an early callback does not occur, then it will be called automatically
  63   // when Finish() is called.  These callbacks will be invoked while the job
  64   // state is Started.
  65   void AppendResultCallback(Callback* aCallback);
  66
  67   // This takes ownership of any result callbacks associated with the given job
  68   // and then appends them to this job's callback list.
  69   void StealResultCallbacksFrom(ServiceWorkerJob* aJob);
  70
  71   // Start the job.  All work will be performed asynchronously on
  72   // the main thread.  The Finish() method must be called exactly
  73   // once after this point.  A final callback must be provided.  It
  74   // will be invoked after all other callbacks have been processed.
  75   void Start(Callback* aFinalCallback);
  76
  77   // Set an internal flag indicating that a started job should finish as
  78   // soon as possible.
  79   void Cancel();
  80
  81  protected:
  82   ServiceWorkerJob(Type aType, nsIPrincipal* aPrincipal,
  83                    const nsACString& aScope, nsCString aScriptSpec);
  84
  85   virtual ~ServiceWorkerJob();
  86
  87   // Invoke the result callbacks immediately.  The job must be in the
  88   // Started state or be canceled and in the Initial state.  The callbacks are
  89   // cleared after being invoked, so subsequent method calls have no effect.
  90   void InvokeResultCallbacks(ErrorResult& aRv);
  91
  92   // Convenience method that converts to ErrorResult and calls real method.
  93   void InvokeResultCallbacks(nsresult aRv);
  94
  95   // Indicate that the job has completed.  The must be called exactly
  96   // once after Start() has initiated job execution.  It may not be
  97   // called until Start() has returned.
  98   void Finish(ErrorResult& aRv);
  99
 100   // Convenience method that converts to ErrorResult and calls real method.
 101   void Finish(nsresult aRv);
 102
 103   // Specific job types should define AsyncExecute to begin their work.
 104   // All errors and successes must result in Finish() being called.
 105   virtual void AsyncExecute() = 0;
 106
 107   const Type mType;
 108   nsCOMPtr<nsIPrincipal> mPrincipal;
 109   const nsCString mScope;
 110   const nsCString mScriptSpec;
 111
 112  private:
 113   RefPtr<Callback> mFinalCallback;
 114   nsTArray<RefPtr<Callback>> mResultCallbackList;
 115   State mState;
 116   bool mCanceled;
 117   bool mResultCallbacksInvoked;
 118
 119  public:
 120   NS_INLINE_DECL_REFCOUNTING(ServiceWorkerJob)
 121 };
 122
 123 }  // namespace dom
 124 }  // namespace mozilla
 125
 126 #endif  // mozilla_dom_serviceworkerjob_h