Skip to content

Commit ffa028d

Browse files
committed
add stability annotations
1 parent 257e871 commit ffa028d

File tree

3 files changed

+83
-85
lines changed

3 files changed

+83
-85
lines changed

library/alloc/src/lib.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@
150150
#![feature(slice_ptr_get)]
151151
#![feature(slice_ptr_len)]
152152
#![feature(slice_range)]
153+
#![feature(stable_wakers)]
153154
#![feature(str_internals)]
154155
#![feature(strict_provenance)]
155156
#![feature(trusted_len)]

library/alloc/src/task.rs

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -121,33 +121,45 @@ impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for RawWaker {
121121
#[inline(always)]
122122
fn raw_waker<W: Wake + Send + Sync + 'static>(waker: Arc<W>) -> RawWaker {
123123
// Increment the reference count of the arc to clone it.
124-
unsafe fn clone_waker<W: Wake + Send + Sync + 'static>(waker: *const ()) -> RawWaker {
124+
unsafe extern "C" fn clone_waker<W: Wake + Send + Sync + 'static>(
125+
waker: *const (),
126+
) -> RawWaker {
125127
unsafe { Arc::increment_strong_count(waker as *const W) };
126128
RawWaker::new(
127129
waker as *const (),
128-
&RawWakerVTable::new(clone_waker::<W>, wake::<W>, wake_by_ref::<W>, drop_waker::<W>),
130+
&RawWakerVTable::new_with_c_abi(
131+
clone_waker::<W>,
132+
wake::<W>,
133+
wake_by_ref::<W>,
134+
drop_waker::<W>,
135+
),
129136
)
130137
}
131138

132139
// Wake by value, moving the Arc into the Wake::wake function
133-
unsafe fn wake<W: Wake + Send + Sync + 'static>(waker: *const ()) {
140+
unsafe extern "C" fn wake<W: Wake + Send + Sync + 'static>(waker: *const ()) {
134141
let waker = unsafe { Arc::from_raw(waker as *const W) };
135142
<W as Wake>::wake(waker);
136143
}
137144

138145
// Wake by reference, wrap the waker in ManuallyDrop to avoid dropping it
139-
unsafe fn wake_by_ref<W: Wake + Send + Sync + 'static>(waker: *const ()) {
146+
unsafe extern "C" fn wake_by_ref<W: Wake + Send + Sync + 'static>(waker: *const ()) {
140147
let waker = unsafe { ManuallyDrop::new(Arc::from_raw(waker as *const W)) };
141148
<W as Wake>::wake_by_ref(&waker);
142149
}
143150

144151
// Decrement the reference count of the Arc on drop
145-
unsafe fn drop_waker<W: Wake + Send + Sync + 'static>(waker: *const ()) {
152+
unsafe extern "C" fn drop_waker<W: Wake + Send + Sync + 'static>(waker: *const ()) {
146153
unsafe { Arc::decrement_strong_count(waker as *const W) };
147154
}
148155

149156
RawWaker::new(
150157
Arc::into_raw(waker) as *const (),
151-
&RawWakerVTable::new(clone_waker::<W>, wake::<W>, wake_by_ref::<W>, drop_waker::<W>),
158+
&RawWakerVTable::new_with_c_abi(
159+
clone_waker::<W>,
160+
wake::<W>,
161+
wake_by_ref::<W>,
162+
drop_waker::<W>,
163+
),
152164
)
153165
}

library/core/src/task/wake.rs

Lines changed: 64 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -63,23 +63,6 @@ impl RawWaker {
6363
}
6464

6565
const RAW_WAKER_VTABLE_V1_PADDING: usize = 0;
66-
67-
/// A virtual function pointer table (vtable) that specifies the behavior
68-
/// of a [`RawWaker`].
69-
///
70-
/// The pointer passed to all functions inside the vtable is the `data` pointer
71-
/// from the enclosing [`RawWaker`] object.
72-
///
73-
/// The functions inside this struct are only intended to be called on the `data`
74-
/// pointer of a properly constructed [`RawWaker`] object from inside the
75-
/// [`RawWaker`] implementation. Calling one of the contained functions using
76-
/// any other `data` pointer will cause undefined behavior.
77-
///
78-
/// These functions must all be thread-safe (even though [`RawWaker`] is
79-
/// <code>\![Send] + \![Sync]</code>)
80-
/// because [`Waker`] is <code>[Send] + [Sync]</code>, and thus wakers may be moved to
81-
/// arbitrary threads or invoked by `&` reference. For example, this means that if the
82-
/// `clone` and `drop` functions manage a reference count, they must do so atomically.
8366
#[stable(feature = "futures_api", since = "1.36.0")]
8467
#[derive(PartialEq, Copy, Clone, Debug)]
8568
#[repr(C)]
@@ -159,18 +142,42 @@ struct RawWakerVTableV2 {
159142
padding: [*const (); 2 + RAW_WAKER_VTABLE_V1_PADDING], // Reserved space for future changes to the v-table, the need for it and amount are debatable.
160143
}
161144

145+
/// A virtual function pointer table (vtable) that specifies the behavior
146+
/// of a [`RawWaker`].
147+
///
148+
/// The pointer passed to all functions inside the vtable is the `data` pointer
149+
/// from the enclosing [`RawWaker`] object.
150+
///
151+
/// The functions inside this struct are only intended to be called on the `data`
152+
/// pointer of a properly constructed [`RawWaker`] object from inside the
153+
/// [`RawWaker`] implementation. Calling one of the contained functions using
154+
/// any other `data` pointer will cause undefined behavior.
155+
///
156+
/// These functions must all be thread-safe (even though [`RawWaker`] is
157+
/// <code>\![Send] + \![Sync]</code>)
158+
/// because [`Waker`] is <code>[Send] + [Sync]</code>, and thus wakers may be moved to
159+
/// arbitrary threads or invoked by `&` reference. For example, this means that if the
160+
/// `clone` and `drop` functions manage a reference count, they must do so atomically.
162161
#[repr(C)]
163162
#[derive(Clone, Copy)]
163+
#[stable(feature = "futures_api", since = "1.36.0")]
164164
pub union RawWakerVTable {
165165
v1: RawWakerVTableV1,
166166
v2: RawWakerVTableV2,
167167
}
168+
#[stable(feature = "futures_api", since = "1.36.0")]
169+
unsafe impl Send for RawWakerVTable {}
170+
#[stable(feature = "futures_api", since = "1.36.0")]
171+
unsafe impl Sync for RawWakerVTable {}
168172

173+
#[stable(feature = "futures_api", since = "1.36.0")]
169174
impl PartialEq for RawWakerVTable {
170175
fn eq(&self, other: &Self) -> bool {
171176
unsafe { self.v2 == other.v2 }
172177
}
173178
}
179+
180+
#[stable(feature = "futures_api", since = "1.36.0")]
174181
impl fmt::Debug for RawWakerVTable {
175182
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
176183
unsafe {
@@ -182,6 +189,21 @@ impl fmt::Debug for RawWakerVTable {
182189
}
183190
}
184191

192+
#[allow(improper_ctypes_definitions)]
193+
/// # Safety
194+
/// This function must only be called with function pointers sourced from the same shared object
195+
unsafe extern "C" fn clone_adapter(
196+
clone: unsafe fn(*const ()) -> RawWaker,
197+
data: *const (),
198+
) -> RawWaker {
199+
unsafe { (clone)(data) }
200+
}
201+
#[allow(improper_ctypes_definitions)]
202+
/// # Safety
203+
/// This function must only be called with function pointers sourced from the same shared object
204+
unsafe extern "C" fn other_adapter(other: unsafe fn(*const ()), data: *const ()) {
205+
unsafe { (other)(data) }
206+
}
185207
impl RawWakerVTable {
186208
/// Creates a new `RawWakerVTable` from the provided `clone`, `wake`,
187209
/// `wake_by_ref`, and `drop` functions.
@@ -192,7 +214,7 @@ impl RawWakerVTable {
192214
/// arbitrary threads or invoked by `&` reference. For example, this means that if the
193215
/// `clone` and `drop` functions manage a reference count, they must do so atomically.
194216
///
195-
/# `clone`
217+
/// # `clone`
196218
///
197219
/// This function will be called when the [`RawWaker`] gets cloned, e.g. when
198220
/// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
@@ -202,7 +224,7 @@ impl RawWakerVTable {
202224
/// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
203225
/// of the same task that would have been awoken by the original [`RawWaker`].
204226
///
205-
/# `wake`
227+
/// # `wake`
206228
///
207229
/// This function will be called when `wake` is called on the [`Waker`].
208230
/// It must wake up the task associated with this [`RawWaker`].
@@ -211,15 +233,15 @@ impl RawWakerVTable {
211233
/// resources that are associated with this instance of a [`RawWaker`] and
212234
/// associated task.
213235
///
214-
/# `wake_by_ref`
236+
/// # `wake_by_ref`
215237
///
216238
/// This function will be called when `wake_by_ref` is called on the [`Waker`].
217239
/// It must wake up the task associated with this [`RawWaker`].
218240
///
219241
/// This function is similar to `wake`, but must not consume the provided data
220242
/// pointer.
221243
///
222-
/# `drop`
244+
/// # `drop`
223245
///
224246
/// This function gets called when a [`Waker`] gets dropped.
225247
///
@@ -229,22 +251,17 @@ impl RawWakerVTable {
229251
#[rustc_promotable]
230252
#[stable(feature = "futures_api", since = "1.36.0")]
231253
#[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
232-
#[deprecated = "This constructor makes slower wakers, use new_with_c_abi instead"]
254+
#[deprecated(
255+
since = "TBD",
256+
note = "This constructor makes slower wakers",
257+
suggestion = "new_with_c_abi"
258+
)]
233259
pub const fn new(
234260
clone: unsafe fn(*const ()) -> RawWaker,
235261
wake: unsafe fn(*const ()),
236262
wake_by_ref: unsafe fn(*const ()),
237263
drop: unsafe fn(*const ()),
238264
) -> Self {
239-
unsafe extern "C" fn clone_adapter(
240-
clone: unsafe fn(*const ()) -> RawWaker,
241-
data: *const (),
242-
) -> RawWaker {
243-
clone(data)
244-
}
245-
unsafe extern "C" fn other_adapter(other: unsafe fn(*const ()), data: *const ()) {
246-
other(data)
247-
}
248265
Self {
249266
v1: RawWakerVTableV1 {
250267
clone,
@@ -267,7 +284,7 @@ impl RawWakerVTable {
267284
/// arbitrary threads or invoked by `&` reference. For example, this means that if the
268285
/// `clone` and `drop` functions manage a reference count, they must do so atomically.
269286
///
270-
/# `clone`
287+
/// # `clone`
271288
///
272289
/// This function will be called when the [`RawWaker`] gets cloned, e.g. when
273290
/// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
@@ -277,7 +294,7 @@ impl RawWakerVTable {
277294
/// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
278295
/// of the same task that would have been awoken by the original [`RawWaker`].
279296
///
280-
/# `wake`
297+
/// # `wake`
281298
///
282299
/// This function will be called when `wake` is called on the [`Waker`].
283300
/// It must wake up the task associated with this [`RawWaker`].
@@ -286,22 +303,24 @@ impl RawWakerVTable {
286303
/// resources that are associated with this instance of a [`RawWaker`] and
287304
/// associated task.
288305
///
289-
/# `wake_by_ref`
306+
/// # `wake_by_ref`
290307
///
291308
/// This function will be called when `wake_by_ref` is called on the [`Waker`].
292309
/// It must wake up the task associated with this [`RawWaker`].
293310
///
294311
/// This function is similar to `wake`, but must not consume the provided data
295312
/// pointer.
296313
///
297-
/# `drop`
314+
/// # `drop`
298315
///
299316
/// This function gets called when a [`Waker`] gets dropped.
300317
///
301318
/// The implementation of this function must make sure to release any
302319
/// resources that are associated with this instance of a [`RawWaker`] and
303320
/// associated task.
304321
#[rustc_promotable]
322+
#[unstable(feature = "stable_wakers", issue = "109706")]
323+
#[rustc_const_unstable(feature = "stable_wakers", issue = "109706")]
305324
pub const fn new_with_c_abi(
306325
clone: unsafe extern "C" fn(*const ()) -> RawWaker,
307326
wake: unsafe extern "C" fn(*const ()),
@@ -345,11 +364,7 @@ impl<'a> Context<'a> {
345364
#[must_use]
346365
#[inline]
347366
pub const fn from_waker(waker: &'a Waker) -> Self {
348-
Context {
349-
waker,
350-
_marker: PhantomData,
351-
_marker2: PhantomData,
352-
}
367+
Context { waker, _marker: PhantomData, _marker2: PhantomData }
353368
}
354369

355370
/// Returns a reference to the [`Waker`] for the current task.
@@ -365,9 +380,7 @@ impl<'a> Context<'a> {
365380
#[stable(feature = "futures_api", since = "1.36.0")]
366381
impl fmt::Debug for Context<'_> {
367382
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
368-
f.debug_struct("Context")
369-
.field("waker", &self.waker)
370-
.finish()
383+
f.debug_struct("Context").field("waker", &self.waker).finish()
371384
}
372385
}
373386

@@ -437,16 +450,9 @@ impl Waker {
437450
unsafe {
438451
match *vtable {
439452
RawWakerVTable {
440-
v1:
441-
RawWakerVTableV1 {
442-
wake,
443-
other_adapter: Some(other_adapter),
444-
..
445-
},
453+
v1: RawWakerVTableV1 { wake, other_adapter: Some(other_adapter), .. },
446454
} => (other_adapter)(wake, data),
447-
RawWakerVTable {
448-
v2: RawWakerVTableV2 { wake, .. },
449-
} => (wake)(data),
455+
RawWakerVTable { v2: RawWakerVTableV2 { wake, .. } } => (wake)(data),
450456
}
451457
};
452458
}
@@ -467,16 +473,9 @@ impl Waker {
467473
unsafe {
468474
match *vtable {
469475
RawWakerVTable {
470-
v1:
471-
RawWakerVTableV1 {
472-
wake_by_ref,
473-
other_adapter: Some(other_adapter),
474-
..
475-
},
476+
v1: RawWakerVTableV1 { wake_by_ref, other_adapter: Some(other_adapter), .. },
476477
} => (other_adapter)(wake_by_ref, data),
477-
RawWakerVTable {
478-
v2: RawWakerVTableV2 { wake_by_ref, .. },
479-
} => (wake_by_ref)(data),
478+
RawWakerVTable { v2: RawWakerVTableV2 { wake_by_ref, .. } } => (wake_by_ref)(data),
480479
}
481480
}
482481
}
@@ -529,16 +528,9 @@ impl Clone for Waker {
529528
waker: unsafe {
530529
match *vtable {
531530
RawWakerVTable {
532-
v1:
533-
RawWakerVTableV1 {
534-
clone,
535-
clone_adapter: Some(clone_adapter),
536-
..
537-
},
531+
v1: RawWakerVTableV1 { clone, clone_adapter: Some(clone_adapter), .. },
538532
} => (clone_adapter)(clone, data),
539-
RawWakerVTable {
540-
v2: RawWakerVTableV2 { clone, .. },
541-
} => (clone)(data),
533+
RawWakerVTable { v2: RawWakerVTableV2 { clone, .. } } => (clone)(data),
542534
}
543535
},
544536
}
@@ -556,16 +548,9 @@ impl Drop for Waker {
556548
unsafe {
557549
match *vtable {
558550
RawWakerVTable {
559-
v1:
560-
RawWakerVTableV1 {
561-
drop,
562-
other_adapter: Some(other_adapter),
563-
..
564-
},
551+
v1: RawWakerVTableV1 { drop, other_adapter: Some(other_adapter), .. },
565552
} => (other_adapter)(drop, data),
566-
RawWakerVTable {
567-
v2: RawWakerVTableV2 { drop, .. },
568-
} => (drop)(data),
553+
RawWakerVTable { v2: RawWakerVTableV2 { drop, .. } } => (drop)(data),
569554
}
570555
}
571556
}

0 commit comments

Comments
 (0)