ipc/glue/BackgroundChild.h

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #ifndef mozilla_ipc_backgroundchild_h__
   6 #define mozilla_ipc_backgroundchild_h__
   7
   8 #include "base/process.h"
   9 #include "mozilla/Attributes.h"
  10 #include "mozilla/ipc/Transport.h"
  11
  12 class nsIDOMBlob;
  13 class nsIIPCBackgroundChildCreateCallback;
  14
  15 namespace mozilla {
  16 namespace dom {
  17
  18 class ContentChild;
  19 class ContentParent;
  20 class PBlobChild;
  21
  22 } // namespace dom
  23
  24 namespace ipc {
  25
  26 class PBackgroundChild;
  27
  28 // This class allows access to the PBackground protocol. PBackground allows
  29 // communication between any thread (in the parent or a child process) and a
  30 // single background thread in the parent process. Each PBackgroundChild
  31 // instance is tied to the thread on which it is created and must not be shared
  32 // across threads. Each PBackgroundChild is unique and valid as long as its
  33 // designated thread lives.
  34 //
  35 // Creation of PBackground is asynchronous. GetForCurrentThread() will return
  36 // null until the sequence is complete. GetOrCreateForCurrentThread() will start
  37 // the creation sequence and will call back via the
  38 // nsIIPCBackgroundChildCreateCallback interface when completed. Thereafter
  39 // (assuming success) GetForCurrentThread() will return the same actor every
  40 // time.
  41 //
  42 // CloseForCurrentThread() will close the current PBackground actor.  Subsequent
  43 // calls to GetForCurrentThread will return null.  CloseForCurrentThread() may
  44 // only be called exactly once for each thread-specific actor.  Currently it is
  45 // illegal to call this before the PBackground actor has been created.
  46 //
  47 // The PBackgroundChild actor and all its sub-protocol actors will be
  48 // automatically destroyed when its designated thread completes.
  49 class BackgroundChild final
  50 {
  51   friend class mozilla::dom::ContentChild;
  52   friend class mozilla::dom::ContentParent;
  53
  54   typedef base::ProcessId ProcessId;
  55   typedef mozilla::ipc::Transport Transport;
  56
  57 public:
  58   // See above.
  59   static PBackgroundChild*
  60   GetForCurrentThread();
  61
  62   // See above.
  63   static bool
  64   GetOrCreateForCurrentThread(nsIIPCBackgroundChildCreateCallback* aCallback);
  65
  66   static mozilla::dom::PBlobChild*
  67   GetOrCreateActorForBlob(PBackgroundChild* aBackgroundActor,
  68                           nsIDOMBlob* aBlob);
  69
  70   // See above.
  71   static void
  72   CloseForCurrentThread();
  73
  74 private:
  75   // Only called by ContentChild or ContentParent.
  76   static void
  77   Startup();
  78
  79   // Only called by ContentChild.
  80   static PBackgroundChild*
  81   Alloc(Transport* aTransport, ProcessId aOtherProcess);
  82 };
  83
  84 } // namespace ipc
  85 } // namespace mozilla
  86
  87 #endif // mozilla_ipc_backgroundchild_h__