js/public/GCAnnotations.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 js_GCAnnotations_h
   8 #define js_GCAnnotations_h
   9
  10 // Set of annotations for the rooting hazard analysis, used to categorize types
  11 // and functions.
  12 #ifdef XGILL_PLUGIN
  13
  14 #  define JS_EXPECT_HAZARDS __attribute__((annotate("Expect Hazards")))
  15
  16 // Mark a type as being a GC thing (eg js::gc::Cell has this annotation).
  17 #  define JS_HAZ_GC_THING __attribute__((annotate("GC Thing")))
  18
  19 // Mark a type as holding a pointer to a GC thing (eg JS::Value has this
  20 // annotation.) "Inherited" by templatized types with
  21 // MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS.
  22 #  define JS_HAZ_GC_POINTER __attribute__((annotate("GC Pointer")))
  23
  24 // Mark a type as a rooted pointer, suitable for use on the stack (eg all
  25 // Rooted<T> instantiations should have this.) "Inherited" by templatized types
  26 // with MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS.
  27 #  define JS_HAZ_ROOTED __attribute__((annotate("Rooted Pointer")))
  28
  29 // Mark a type as something that should not be held live across a GC, but which
  30 // is not itself a GC pointer. Note that this property is *not* inherited by
  31 // templatized types with MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS.
  32 #  define JS_HAZ_GC_INVALIDATED __attribute__((annotate("Invalidated by GC")))
  33
  34 // Mark a class as a base class of rooted types, eg CustomAutoRooter. All
  35 // descendants of this class will be considered rooted, though classes that
  36 // merely contain these as a field member will not be. "Inherited" by
  37 // templatized types with MOZ_INHERIT_TYPE_ANNOTATIONS_FROM_TEMPLATE_ARGS
  38 #  define JS_HAZ_ROOTED_BASE __attribute__((annotate("Rooted Base")))
  39
  40 // Mark a type that would otherwise be considered a GC Pointer (eg because it
  41 // contains a JS::Value field) as a non-GC pointer. It is handled almost the
  42 // same in the analysis as a rooted pointer, except it will not be reported as
  43 // an unnecessary root if used across a GC call. This should rarely be used,
  44 // but makes sense for something like ErrorResult, which only contains a GC
  45 // pointer when it holds an exception (and it does its own rooting,
  46 // conditionally.)
  47 #  define JS_HAZ_NON_GC_POINTER \
  48     __attribute__((annotate("Suppressed GC Pointer")))
  49
  50 // Mark a function as something that runs a garbage collection, potentially
  51 // invalidating GC pointers.
  52 #  define JS_HAZ_GC_CALL __attribute__((annotate("GC Call")))
  53
  54 // Mark an RAII class as suppressing GC within its scope.
  55 #  define JS_HAZ_GC_SUPPRESSED __attribute__((annotate("Suppress GC")))
  56
  57 // Mark a function as one that can run script if called.  This obviously
  58 // subsumes JS_HAZ_GC_CALL, since anything that can run script can GC.`
  59 #  define JS_HAZ_CAN_RUN_SCRIPT __attribute__((annotate("Can run script")))
  60
  61 // Mark a function as able to call JSNatives. Otherwise, JSNatives don't show
  62 // up in the callgraph. This doesn't matter for the can-GC analysis, but it is
  63 // very nice for other uses of the callgraph.
  64 #  define JS_HAZ_JSNATIVE_CALLER __attribute__((annotate("Calls JSNatives")))
  65
  66 #else
  67
  68 #  define JS_EXPECT_HAZARDS
  69 #  define JS_HAZ_GC_THING
  70 #  define JS_HAZ_GC_POINTER
  71 #  define JS_HAZ_ROOTED
  72 #  define JS_HAZ_GC_INVALIDATED
  73 #  define JS_HAZ_ROOTED_BASE
  74 #  define JS_HAZ_NON_GC_POINTER
  75 #  define JS_HAZ_GC_CALL
  76 #  define JS_HAZ_GC_SUPPRESSED
  77 #  define JS_HAZ_CAN_RUN_SCRIPT
  78 #  define JS_HAZ_JSNATIVE_CALLER
  79
  80 #endif
  81
  82 #endif /* js_GCAnnotations_h */