layout/style/ServoBindingTypes.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 /* C++ types corresponding to Servo and Gecko types used across bindings,
   8    with some annotations to indicate ownership expectations */
   9
  10 // This file defines RefPtrTraits and UniquePtrTraits helpers for a number of
  11 // C++ types used to represent strong, and owning references to Servo and Gecko
  12 // objects that might be used across bindings and FFI.
  13 //
  14 // The strong, and owned reference types should be used in FFI function
  15 // signatures where possible, to help indicate the ownership properties that
  16 // both sides of the function call must adhere to.
  17 //
  18 // Using these types in C++ ========================
  19 //
  20 // The Strong types are a C++ struct that wraps a raw pointer.  When receiving a
  21 // Strong value from a Servo_* FFI function, you must call Consume() on it to
  22 // convert it into an already_AddRefed<RawServo{Type}>, otherwise it will leak.
  23 //
  24 // We don't currently have any cases where we pass a Strong value to Servo; this
  25 // could be done by creating a RawServo{Type}Strong struct value whose mPtr is
  26 // initialized to the result of calling `.forget().take()` on a
  27 // RefPtr<RawServo{Type}>, but it's probably easier just to pass a raw pointer
  28 // and let the Rust code turn it into an Arc.
  29 //
  30 // TODO(heycam): We should perhaps have a similar struct for Owned types with a
  31 // Consume() method to convert them into a UniquePtr.  The struct for Strong
  32 // types at least have [[nodiscard]] on them.
  33 //
  34 // Using these types in Rust =========================
  35 //
  36 // The FFI type names are available in Rust in the gecko_bindings::bindings mod,
  37 // which is generated by servo/components/style/build_gecko.rs.
  38 //
  39 // Borrowed types in rust are represented by &T, Option<&T>, &mut T, and
  40 // Option<&mut T>.
  41 //
  42 // In C++ you should write them as const pointers (for &T and Option<&T>) or
  43 // non-const pointers (for &mut T and Option<&mut T>).
  44 //
  45 // The Strong types are defined as gecko_bindings::sugar::ownership::Strong<T>.
  46 //
  47 // This is an FFI safe type that represents the value with a strong reference
  48 // already added to it.  Dropping a Strong<T> will leak the strong reference.
  49 //
  50 // The Owned types are defined as gecko_bindings::sugar::ownership::Owned<T>
  51 // (or OwnedOrNull<T>). This is another FFI safe type that represents the owning
  52 // reference to the value.  Dropping an Owned<T> will leak the value.
  53
  54 #ifndef mozilla_ServoBindingTypes_h
  55 #define mozilla_ServoBindingTypes_h
  56
  57 #include "mozilla/RefPtr.h"
  58 #include "mozilla/ServoTypes.h"
  59 #include "mozilla/UniquePtr.h"
  60 #include "mozilla/gfx/Types.h"
  61 #include "nsCSSPropertyID.h"
  62 #include "nsStyleAutoArray.h"
  63 #include "nsTArray.h"
  64
  65 // Forward declarations.
  66
  67 class nsCSSPropertyIDSet;
  68 class nsCSSValue;
  69 class nsINode;
  70 class nsPresContext;
  71 struct nsFontFaceRuleContainer;
  72
  73 namespace mozilla {
  74 class ComputedStyle;
  75 class ServoElementSnapshot;
  76 struct AnimationPropertySegment;
  77 struct ComputedTiming;
  78 struct Keyframe;
  79 struct PropertyStyleAnimationValuePair;
  80 struct PropertyValuePair;
  81 struct StyleAnimation;
  82 struct StyleCssUrlData;
  83 struct StyleAnimationValue;
  84 struct StyleStylesheetContents;
  85 struct URLExtraData;
  86 using ComputedKeyframeValues = nsTArray<PropertyStyleAnimationValuePair>;
  87 using GfxMatrix4x4 = mozilla::gfx::Float[16];
  88
  89 namespace dom {
  90 class StyleChildrenIterator;
  91 class Document;
  92 class Element;
  93 }  // namespace dom
  94
  95 }  // namespace mozilla
  96
  97 #define SERVO_ARC_TYPE(name_, type_)                                    \
  98   extern "C" {                                                          \
  99   void Servo_##name_##_AddRef(const type_*);                            \
 100   void Servo_##name_##_Release(const type_*);                           \
 101   }                                                                     \
 102   namespace mozilla {                                                   \
 103   template <>                                                           \
 104   struct RefPtrTraits<type_> {                                          \
 105     static void AddRef(type_* aPtr) { Servo_##name_##_AddRef(aPtr); }   \
 106     static void Release(type_* aPtr) { Servo_##name_##_Release(aPtr); } \
 107   };                                                                    \
 108   }
 109 #define SERVO_LOCKED_ARC_TYPE(name_) \
 110   namespace mozilla {                \
 111   struct StyleLocked##name_;         \
 112   }                                  \
 113   SERVO_ARC_TYPE(name_, mozilla::StyleLocked##name_)
 114 #include "mozilla/ServoLockedArcTypeList.h"
 115
 116 #define UNLOCKED_RULE_TYPE(name_) \
 117   namespace mozilla {             \
 118   struct Style##name_##Rule;      \
 119   }                               \
 120   SERVO_ARC_TYPE(name_##Rule, mozilla::Style##name_##Rule)
 121
 122 UNLOCKED_RULE_TYPE(Property)
 123 UNLOCKED_RULE_TYPE(LayerBlock)
 124 UNLOCKED_RULE_TYPE(LayerStatement)
 125 UNLOCKED_RULE_TYPE(Namespace)
 126 UNLOCKED_RULE_TYPE(Container)
 127 UNLOCKED_RULE_TYPE(Media)
 128 UNLOCKED_RULE_TYPE(Supports)
 129 UNLOCKED_RULE_TYPE(Document)
 130 UNLOCKED_RULE_TYPE(FontFeatureValues)
 131 UNLOCKED_RULE_TYPE(FontPaletteValues)
 132
 133 SERVO_ARC_TYPE(AnimationValue, mozilla::StyleAnimationValue)
 134 SERVO_ARC_TYPE(ComputedStyle, mozilla::ComputedStyle)
 135 SERVO_ARC_TYPE(CssUrlData, mozilla::StyleCssUrlData)
 136 SERVO_ARC_TYPE(StyleSheetContents, mozilla::StyleStylesheetContents)
 137
 138 #undef UNLOCKED_RULE_TYPE
 139 #undef SERVO_LOCKED_ARC_TYPE
 140 #undef SERVO_ARC_TYPE
 141
 142 #define SERVO_BOXED_TYPE(name_, type_)                                        \
 143   namespace mozilla {                                                         \
 144   struct Style##type_;                                                        \
 145   }                                                                           \
 146   extern "C" void Servo_##name_##_Drop(mozilla::Style##type_*);               \
 147   namespace mozilla {                                                         \
 148   template <>                                                                 \
 149   class DefaultDelete<Style##type_> {                                         \
 150    public:                                                                    \
 151     void operator()(Style##type_* aPtr) const { Servo_##name_##_Drop(aPtr); } \
 152   };                                                                          \
 153   }
 154 #include "mozilla/ServoBoxedTypeList.h"
 155 #undef SERVO_BOXED_TYPE
 156
 157 // Other special cases.
 158
 159 struct RawServoAnimationValueTable;
 160
 161 #endif  // mozilla_ServoBindingTypes_h