js/public/RealmIterators.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 /*
   8  * Various interfaces to iterate over the Realms given various context such as
   9  * principals, compartments and GC zones.
  10  */
  11
  12 #ifndef js_RealmIterators_h
  13 #define js_RealmIterators_h
  14
  15 #include "js/GCAPI.h"
  16 #include "js/TypeDecls.h"
  17
  18 struct JSPrincipals;
  19
  20 namespace JS {
  21
  22 class JS_PUBLIC_API AutoRequireNoGC;
  23
  24 using IterateRealmCallback = void (*)(JSContext* cx, void* data, Realm* realm,
  25                                       const AutoRequireNoGC& nogc);
  26
  27 /**
  28  * This function calls |realmCallback| on every realm. Beware that there is no
  29  * guarantee that the realm will survive after the callback returns. Also,
  30  * barriers are disabled via the TraceSession.
  31  */
  32 extern JS_PUBLIC_API void IterateRealms(JSContext* cx, void* data,
  33                                         IterateRealmCallback realmCallback);
  34
  35 /**
  36  * Like IterateRealms, but only call the callback for realms using |principals|.
  37  */
  38 extern JS_PUBLIC_API void IterateRealmsWithPrincipals(
  39     JSContext* cx, JSPrincipals* principals, void* data,
  40     IterateRealmCallback realmCallback);
  41
  42 /**
  43  * Like IterateRealms, but only iterates realms in |compartment|.
  44  */
  45 extern JS_PUBLIC_API void IterateRealmsInCompartment(
  46     JSContext* cx, JS::Compartment* compartment, void* data,
  47     IterateRealmCallback realmCallback);
  48
  49 /**
  50  * An enum that JSIterateCompartmentCallback can return to indicate
  51  * whether to keep iterating.
  52  */
  53 enum class CompartmentIterResult { KeepGoing, Stop };
  54
  55 }  // namespace JS
  56
  57 using JSIterateCompartmentCallback =
  58     JS::CompartmentIterResult (*)(JSContext*, void*, JS::Compartment*);
  59
  60 /**
  61  * This function calls |compartmentCallback| on every compartment until either
  62  * all compartments have been iterated or CompartmentIterResult::Stop is
  63  * returned. Beware that there is no guarantee that the compartment will survive
  64  * after the callback returns. Also, barriers are disabled via the TraceSession.
  65  */
  66 extern JS_PUBLIC_API void JS_IterateCompartments(
  67     JSContext* cx, void* data,
  68     JSIterateCompartmentCallback compartmentCallback);
  69
  70 /**
  71  * This function calls |compartmentCallback| on every compartment in the given
  72  * zone until either all compartments have been iterated or
  73  * CompartmentIterResult::Stop is returned. Beware that there is no guarantee
  74  * that the compartment will survive after the callback returns. Also, barriers
  75  * are disabled via the TraceSession.
  76  */
  77 extern JS_PUBLIC_API void JS_IterateCompartmentsInZone(
  78     JSContext* cx, JS::Zone* zone, void* data,
  79     JSIterateCompartmentCallback compartmentCallback);
  80
  81 #endif /* js_RealmIterators_h */