1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/* C++ types corresponding to Servo and Gecko types used across bindings,
with some annotations to indicate ownership expectations */
// This file defines a number of C++ types used to represent strong, and owning
// references to Servo and Gecko objects that might be used across bindings and
// FFI.
//
// By convention, the types defined here are named "RawServo{Type}" and
// "RawGecko{Type}". The {Type} should be something close to the real Rust or
// C++ name of the type, but need not be. The "Raw" is really just used to
// avoid clashing with other names.
//
// For Servo types, each "RawServo{ServoTypeName}" is generated as an opaque,
// declared but not defined struct.
//
// For Gecko types, each "RawGecko{GeckoTypeName}" is a typedef that aliases
// the actual C++ type.
//
// Each of these types can have a number of different typedefs generated for
// them, representing different notions of ownership when passing or receiving
// these values across bindings and FFI:
//
// RawServo{Type}Strong
// strong reference to an Arc-managed value
//
// All of these strong, and owned types are generated by adding
// entries to one of these files:
//
// ServoArcTypeList.h
// generates the Strong type
//
//
// The strong, and owned reference types should be used in FFI function
// signatures where possible, to help indicate the ownership properties that
// both sides of the function call must adhere to.
//
// There are some special cases defined at the bottom of this file that don't
// fit neatly into these three categories.
//
//
// Using these types in C++ ========================
//
// The Strong types are a C++ struct that wraps a raw pointer. When receiving a
// Strong value from a Servo_* FFI function, you must call Consume() on it to
// convert it into an already_AddRefed<RawServo{Type}>, otherwise it will leak.
//
// We don't currently have any cases where we pass a Strong value to Servo; this
// could be done by creating a RawServo{Type}Strong struct value whose mPtr is
// initialized to the result of calling `.forget().take()` on a
// RefPtr<RawServo{Type}>, but it's probably easier just to pass a raw pointer
// and let the Rust code turn it into an Arc.
//
// TODO(heycam): We should perhaps have a similar struct for Owned types with a
// Consume() method to convert them into a UniquePtr. The struct for Strong
// types at least have MOZ_MUST_USE_TYPE on them.
//
//
// Using these types in Rust =========================
//
// The FFI type names are available in Rust in the gecko_bindings::bindings mod,
// which is generated by servo/components/style/build_gecko.rs.
//
// Borrowed types in rust are represented by &T, Option<&T>, &mut T, and
// Option<&mut T>.
//
// In C++ you should write them as const pointers (for &T and Option<&T>) or
// non-const pointers (for &mut T and Option<&mut T>).
//
// The Strong types are defined as gecko_bindings::sugar::ownership::Strong<T>.
//
// This is an FFI safe type that represents the value with a strong reference
// already added to it. Dropping a Strong<T> will leak the strong reference.
//
// A RawServoFooStrong received from FFI can be converted into a
// `RawOffsetArc<Foo>` by calling `into_arc()` or `into_arc_opt()` on it.
// To pass a RawServoFooStrong back to Gecko, call `into_strong()` on the
// `Arc<Foo>`.
//
// The Owned types are defined as gecko_bindings::sugar::ownership::Owned<T>
// (or OwnedOrNull<T>).
//
// This is another FFI safe type that represents the owning reference to the
// value. Dropping an Owned<T> will leak the value.
//
// An Owned<RawServoFoo> received from FFI can be converted into a `Box<Foo>`
// by calling `into_box()`. To pass an Owned<RawServoFoo> back to Gecko, call
// `HasBoxFFI::into_ffi()` passing in the `Box<Foo>` value.
//
// Reading through servo/components/style/gecko_bindings/sugar/ownership.rs
// is also instructive in understanding all this.
#ifndef mozilla_ServoBindingTypes_h
#define mozilla_ServoBindingTypes_h
#include "mozilla/RefPtr.h"
#include "mozilla/ServoTypes.h"
#include "mozilla/UniquePtr.h"
#include "mozilla/gfx/Types.h"
#include "nsCSSPropertyID.h"
#include "nsStyleAutoArray.h"
#include "nsTArray.h"
// Forward declarations.
#define SERVO_ARC_TYPE(name_, type_) struct type_;
#include "mozilla/ServoArcTypeList.h"
#undef SERVO_ARC_TYPE
class nsCSSPropertyIDSet;
class nsCSSValue;
class nsINode;
class nsPresContext;
struct nsFontFaceRuleContainer;
struct nsTimingFunction;
namespace mozilla {
class ComputedStyle;
class ServoElementSnapshot;
struct AnimationPropertySegment;
struct ComputedTiming;
struct Keyframe;
struct PropertyStyleAnimationValuePair;
struct PropertyValuePair;
struct StyleAnimation;
struct URLExtraData;
using ComputedKeyframeValues = nsTArray<PropertyStyleAnimationValuePair>;
using GfxMatrix4x4 = mozilla::gfx::Float[16];
namespace dom {
class StyleChildrenIterator;
class Document;
class Element;
} // namespace dom
} // namespace mozilla
#define SERVO_ARC_TYPE(name_, type_) \
extern "C" { \
void Servo_##name_##_AddRef(const type_*); \
void Servo_##name_##_Release(const type_*); \
} \
namespace mozilla { \
template <> \
struct RefPtrTraits<type_> { \
static void AddRef(type_* aPtr) { Servo_##name_##_AddRef(aPtr); } \
static void Release(type_* aPtr) { Servo_##name_##_Release(aPtr); } \
}; \
}
#include "mozilla/ServoArcTypeList.h"
SERVO_ARC_TYPE(ComputedStyle, mozilla::ComputedStyle)
#undef SERVO_ARC_TYPE
#define SERVO_BOXED_TYPE(name_, type_) \
struct type_; \
extern "C" void Servo_##name_##_Drop(type_*); \
namespace mozilla { \
template <> \
class DefaultDelete<type_> { \
public: \
void operator()(type_* aPtr) const { Servo_##name_##_Drop(aPtr); } \
}; \
}
#include "mozilla/ServoBoxedTypeList.h"
#undef SERVO_BOXED_TYPE
// Other special cases.
struct RawServoAnimationValueTable;
#endif // mozilla_ServoBindingTypes_h
|
