foundationdb/
future.rs

1// Copyright 2018 foundationdb-rs developers, https://github.com/Clikengo/foundationdb-rs/graphs/contributors
2// Copyright 2013-2018 Apple, Inc and the FoundationDB project authors.
3//
4// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
5// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
6// http://opensource.org/licenses/MIT>, at your option. This file may not be
7// copied, modified, or distributed except according to those terms.
8
9//! Most functions in the FoundationDB API are asynchronous, meaning that they
10//! may return to the caller before actually delivering their Fdbresult.
11//!
12//! These functions always return FDBFuture*. An FDBFuture object represents a
13//! Fdbresult value or error to be delivered at some future time. You can wait for
14//! a Future to be “ready” – to have a value or error delivered – by setting a
15//! callback function, or by blocking a thread, or by polling. Once a Future is
16//! ready, you can extract either an error code or a value of the appropriate
17//! type (the documentation for the original function will tell you which
18//! fdb_future_get_*() function you should call).
19//!
20//! Futures make it easy to do multiple operations in parallel, by calling several
21//! asynchronous functions before waiting for any of the Fdbresults. This can be
22//! important for reducing the latency of transactions.
23//!
24
25use std::convert::TryFrom;
26use std::ffi::CStr;
27use std::fmt;
28use std::ops::Deref;
29use std::os::raw::c_char;
30use std::pin::Pin;
31use std::ptr::NonNull;
32use std::sync::Arc;
33
34#[cfg_api_versions(min = 700)]
35pub use crate::fdb_keys::FdbKeys;
36use crate::from_raw_fdb_slice;
37#[cfg_api_versions(min = 710)]
38pub use crate::mapped_key_values::MappedKeyValues;
39use fdb_sys::if_cfg_api_versions;
40use foundationdb_macros::cfg_api_versions;
41use foundationdb_sys as fdb_sys;
42use futures::prelude::*;
43use futures::task::{AtomicWaker, Context, Poll};
44
45use crate::{FdbError, FdbResult, error};
46
47/// An opaque type that represents a Future in the FoundationDB C API.
48pub struct FdbFutureHandle(NonNull<fdb_sys::FDBFuture>);
49
50impl FdbFutureHandle {
51    pub const fn as_ptr(&self) -> *mut fdb_sys::FDBFuture {
52        self.0.as_ptr()
53    }
54}
55unsafe impl Sync for FdbFutureHandle {}
56unsafe impl Send for FdbFutureHandle {}
57impl Drop for FdbFutureHandle {
58    fn drop(&mut self) {
59        // `fdb_future_destroy` cancels the future, so we don't need to call
60        // `fdb_future_cancel` explicitly.
61        unsafe { fdb_sys::fdb_future_destroy(self.as_ptr()) }
62    }
63}
64
65/// An opaque type that represents a pending Future that will be converted to a
66/// predefined result type.
67///
68/// Non owned result type (Fdb
69pub struct FdbFuture<T> {
70    f: Option<FdbFutureHandle>,
71    waker: Option<Arc<AtomicWaker>>,
72    phantom: std::marker::PhantomData<T>,
73}
74
75impl<T> FdbFuture<T>
76where
77    T: TryFrom<FdbFutureHandle, Error = FdbError> + Unpin,
78{
79    pub fn new(f: *mut fdb_sys::FDBFuture) -> Self {
80        Self {
81            f: Some(FdbFutureHandle(
82                NonNull::new(f).expect("FDBFuture to not be null"),
83            )),
84            waker: None,
85            phantom: std::marker::PhantomData,
86        }
87    }
88}
89
90impl<T> Future for FdbFuture<T>
91where
92    T: TryFrom<FdbFutureHandle, Error = FdbError> + Unpin,
93{
94    type Output = FdbResult<T>;
95
96    #[cfg_attr(
97        feature = "trace",
98        tracing::instrument(level = "debug", skip(self, cx))
99    )]
100    fn poll(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<FdbResult<T>> {
101        let f_ptr = self.f.as_ref().expect("cannot poll after resolve").as_ptr();
102        if poll_ready(
103            &mut self.waker,
104            cx,
105            || unsafe { fdb_sys::fdb_future_is_ready(f_ptr) != 0 },
106            |network_waker| {
107                let network_waker_ptr = Arc::into_raw(network_waker);
108                unsafe {
109                    fdb_sys::fdb_future_set_callback(
110                        f_ptr,
111                        Some(fdb_future_callback),
112                        network_waker_ptr as *mut _,
113                    );
114                }
115            },
116        )
117        .is_pending()
118        {
119            return Poll::Pending;
120        }
121        Poll::Ready(
122            error::eval(unsafe { fdb_sys::fdb_future_get_error(f_ptr) })
123                .and_then(|()| T::try_from(self.f.take().expect("self.f.is_some()"))),
124        )
125    }
126}
127
128fn poll_ready(
129    waker: &mut Option<Arc<AtomicWaker>>,
130    cx: &Context<'_>,
131    mut is_ready: impl FnMut() -> bool,
132    set_callback: impl FnOnce(Arc<AtomicWaker>),
133) -> Poll<()> {
134    if is_ready() {
135        return Poll::Ready(());
136    }
137    let mut register = false;
138    let waker = waker.get_or_insert_with(|| {
139        register = true;
140        Arc::new(AtomicWaker::new())
141    });
142    waker.register(cx.waker());
143    if register {
144        set_callback(Arc::clone(waker));
145    }
146    // Completion may have consumed the previous task's waker before registration.
147    // Recheck readiness so the one-shot callback cannot leave this task pending.
148    if is_ready() {
149        Poll::Ready(())
150    } else {
151        Poll::Pending
152    }
153}
154
155pub static CUSTOM_EXECUTOR_HOOK: std::sync::OnceLock<fn()> = std::sync::OnceLock::new();
156
157// The callback from fdb C API can be called from multiple threads. so this callback should be
158// thread-safe.
159extern "C" fn fdb_future_callback(
160    _f: *mut fdb_sys::FDBFuture,
161    callback_parameter: *mut ::std::os::raw::c_void,
162) {
163    // resolve all wakeup chain
164    let network_waker: Arc<AtomicWaker> = unsafe { Arc::from_raw(callback_parameter as *const _) };
165    network_waker.wake();
166
167    // polling phase for a custom executor (e.g. the simulation)
168    if let Some(poll_pending_tasks) = CUSTOM_EXECUTOR_HOOK.get() {
169        poll_pending_tasks();
170    }
171}
172
173/// A slice of bytes owned by a foundationDB future
174pub struct FdbSlice {
175    _f: FdbFutureHandle,
176    value: *const u8,
177    len: i32,
178}
179unsafe impl Sync for FdbSlice {}
180unsafe impl Send for FdbSlice {}
181
182impl Deref for FdbSlice {
183    type Target = [u8];
184    fn deref(&self) -> &Self::Target {
185        from_raw_fdb_slice(self.value, self.len as usize)
186    }
187}
188impl AsRef<[u8]> for FdbSlice {
189    fn as_ref(&self) -> &[u8] {
190        self.deref()
191    }
192}
193
194impl TryFrom<FdbFutureHandle> for FdbSlice {
195    type Error = FdbError;
196
197    fn try_from(f: FdbFutureHandle) -> FdbResult<Self> {
198        let mut value = std::ptr::null();
199        let mut len = 0;
200
201        error::eval(unsafe { fdb_sys::fdb_future_get_key(f.as_ptr(), &mut value, &mut len) })?;
202
203        Ok(FdbSlice { _f: f, value, len })
204    }
205}
206
207impl TryFrom<FdbFutureHandle> for Option<FdbSlice> {
208    type Error = FdbError;
209
210    fn try_from(f: FdbFutureHandle) -> FdbResult<Self> {
211        let mut present = 0;
212        let mut value = std::ptr::null();
213        let mut len = 0;
214
215        error::eval(unsafe {
216            fdb_sys::fdb_future_get_value(f.as_ptr(), &mut present, &mut value, &mut len)
217        })?;
218
219        Ok(if present == 0 {
220            None
221        } else {
222            Some(FdbSlice { _f: f, value, len })
223        })
224    }
225}
226
227/// A slice of addresses owned by a foundationDB future
228pub struct FdbAddresses {
229    _f: FdbFutureHandle,
230    strings: *const FdbAddress,
231    len: i32,
232}
233unsafe impl Sync for FdbAddresses {}
234unsafe impl Send for FdbAddresses {}
235
236impl TryFrom<FdbFutureHandle> for FdbAddresses {
237    type Error = FdbError;
238
239    fn try_from(f: FdbFutureHandle) -> FdbResult<Self> {
240        let mut strings: *mut *const c_char = std::ptr::null_mut();
241        let mut len = 0;
242
243        error::eval(unsafe {
244            fdb_sys::fdb_future_get_string_array(f.as_ptr(), &mut strings, &mut len)
245        })?;
246
247        Ok(FdbAddresses {
248            _f: f,
249            strings: strings as *const FdbAddress,
250            len,
251        })
252    }
253}
254
255impl Deref for FdbAddresses {
256    type Target = [FdbAddress];
257
258    fn deref(&self) -> &Self::Target {
259        assert_eq_size!(FdbAddress, *const c_char);
260        assert_eq_align!(FdbAddress, u8);
261        from_raw_fdb_slice(self.strings, self.len as usize)
262    }
263}
264impl AsRef<[FdbAddress]> for FdbAddresses {
265    fn as_ref(&self) -> &[FdbAddress] {
266        self.deref()
267    }
268}
269
270/// An address owned by a foundationDB future
271///
272/// Because the data it represent is owned by the future in FdbAddresses, you
273/// can never own a FdbAddress directly, you can only have references to it.
274/// This way, you can never obtain a lifetime greater than the lifetime of the
275/// slice that gave you access to it.
276#[repr(C, packed)]
277pub struct FdbAddress {
278    c_str: *const c_char,
279}
280
281impl Deref for FdbAddress {
282    type Target = CStr;
283
284    fn deref(&self) -> &CStr {
285        unsafe { std::ffi::CStr::from_ptr(self.c_str) }
286    }
287}
288impl AsRef<CStr> for FdbAddress {
289    fn as_ref(&self) -> &CStr {
290        self.deref()
291    }
292}
293
294/// An slice of keyvalues owned by a foundationDB future
295pub struct FdbValues {
296    _f: FdbFutureHandle,
297    keyvalues: *const FdbKeyValue,
298    len: i32,
299    more: bool,
300}
301unsafe impl Sync for FdbValues {}
302unsafe impl Send for FdbValues {}
303
304impl FdbValues {
305    /// `true` if there is another range after this one
306    pub fn more(&self) -> bool {
307        self.more
308    }
309}
310
311impl TryFrom<FdbFutureHandle> for FdbValues {
312    type Error = FdbError;
313    fn try_from(f: FdbFutureHandle) -> FdbResult<Self> {
314        let mut keyvalues = std::ptr::null();
315        let mut len = 0;
316        let mut more = 0;
317
318        unsafe {
319            error::eval(fdb_sys::fdb_future_get_keyvalue_array(
320                f.as_ptr(),
321                &mut keyvalues,
322                &mut len,
323                &mut more,
324            ))?
325        }
326
327        Ok(FdbValues {
328            _f: f,
329            keyvalues: keyvalues as *const FdbKeyValue,
330            len,
331            more: more != 0,
332        })
333    }
334}
335
336impl Deref for FdbValues {
337    type Target = [FdbKeyValue];
338    fn deref(&self) -> &Self::Target {
339        assert_eq_size!(FdbKeyValue, fdb_sys::FDBKeyValue);
340        assert_eq_align!(FdbKeyValue, u8);
341
342        from_raw_fdb_slice(self.keyvalues, self.len as usize)
343    }
344}
345impl AsRef<[FdbKeyValue]> for FdbValues {
346    fn as_ref(&self) -> &[FdbKeyValue] {
347        self.deref()
348    }
349}
350
351impl<'a> IntoIterator for &'a FdbValues {
352    type Item = &'a FdbKeyValue;
353    type IntoIter = std::slice::Iter<'a, FdbKeyValue>;
354
355    fn into_iter(self) -> Self::IntoIter {
356        self.deref().iter()
357    }
358}
359impl IntoIterator for FdbValues {
360    type Item = FdbValue;
361    type IntoIter = FdbValuesIter;
362
363    fn into_iter(self) -> Self::IntoIter {
364        FdbValuesIter {
365            f: Arc::new(self._f),
366            keyvalues: self.keyvalues,
367            len: self.len,
368            pos: 0,
369        }
370    }
371}
372
373/// An iterator of keyvalues owned by a foundationDB future
374pub struct FdbValuesIter {
375    f: Arc<FdbFutureHandle>,
376    keyvalues: *const FdbKeyValue,
377    len: i32,
378    pos: i32,
379}
380
381unsafe impl Send for FdbValuesIter {}
382
383impl Iterator for FdbValuesIter {
384    type Item = FdbValue;
385    fn next(&mut self) -> Option<Self::Item> {
386        #[allow(clippy::iter_nth_zero)]
387        self.nth(0)
388    }
389
390    fn nth(&mut self, n: usize) -> Option<Self::Item> {
391        let pos = (self.pos as usize).checked_add(n);
392        match pos {
393            Some(pos) if pos < self.len as usize => {
394                // safe because pos < self.len
395                let keyvalue = unsafe { self.keyvalues.add(pos) };
396                self.pos = pos as i32 + 1;
397
398                Some(FdbValue {
399                    _f: self.f.clone(),
400                    keyvalue,
401                })
402            }
403            _ => {
404                self.pos = self.len;
405                None
406            }
407        }
408    }
409
410    fn size_hint(&self) -> (usize, Option<usize>) {
411        let rem = (self.len - self.pos) as usize;
412        (rem, Some(rem))
413    }
414}
415impl ExactSizeIterator for FdbValuesIter {
416    #[inline]
417    fn len(&self) -> usize {
418        (self.len - self.pos) as usize
419    }
420}
421impl DoubleEndedIterator for FdbValuesIter {
422    fn next_back(&mut self) -> Option<Self::Item> {
423        self.nth_back(0)
424    }
425
426    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
427        if n < self.len() {
428            self.len -= 1 + n as i32;
429            // safe because len < original len
430            let keyvalue = unsafe { self.keyvalues.add(self.len as usize) };
431            Some(FdbValue {
432                _f: self.f.clone(),
433                keyvalue,
434            })
435        } else {
436            self.pos = self.len;
437            None
438        }
439    }
440}
441
442/// A keyvalue you can own
443///
444/// Until dropped, this might prevent multiple key/values from beeing freed.
445/// (i.e. the future that own the data is dropped once all data it provided is dropped)
446pub struct FdbValue {
447    _f: Arc<FdbFutureHandle>,
448    keyvalue: *const FdbKeyValue,
449}
450
451unsafe impl Send for FdbValue {}
452
453impl Deref for FdbValue {
454    type Target = FdbKeyValue;
455    fn deref(&self) -> &Self::Target {
456        assert_eq_size!(FdbKeyValue, fdb_sys::FDBKeyValue);
457        assert_eq_align!(FdbKeyValue, u8);
458        unsafe { &*self.keyvalue }
459    }
460}
461impl AsRef<FdbKeyValue> for FdbValue {
462    fn as_ref(&self) -> &FdbKeyValue {
463        self.deref()
464    }
465}
466impl PartialEq for FdbValue {
467    fn eq(&self, other: &Self) -> bool {
468        self.deref() == other.deref()
469    }
470}
471impl Eq for FdbValue {}
472impl fmt::Debug for FdbValue {
473    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
474        self.deref().fmt(f)
475    }
476}
477
478/// A keyvalue owned by a foundationDB future
479///
480/// Because the data it represent is owned by the future in FdbValues, you
481/// can never own a FdbKeyValue directly, you can only have references to it.
482/// This way, you can never obtain a lifetime greater than the lifetime of the
483/// slice that gave you access to it.
484#[repr(C, packed)]
485pub struct FdbKeyValue(fdb_sys::FDBKeyValue);
486
487impl FdbKeyValue {
488    /// key
489    pub fn key(&self) -> &[u8] {
490        // This cast to `*const u8` isn't unnecessary in all configurations.
491        #[allow(clippy::unnecessary_cast)]
492        from_raw_fdb_slice(self.0.key as *const u8, self.0.key_length as usize)
493    }
494
495    /// value
496    pub fn value(&self) -> &[u8] {
497        // This cast to `*const u8` isn't unnecessary in all configurations.
498        #[allow(clippy::unnecessary_cast)]
499        from_raw_fdb_slice(self.0.value as *const u8, self.0.value_length as usize)
500    }
501}
502
503impl PartialEq for FdbKeyValue {
504    fn eq(&self, other: &Self) -> bool {
505        (self.key(), self.value()) == (other.key(), other.value())
506    }
507}
508impl Eq for FdbKeyValue {}
509impl fmt::Debug for FdbKeyValue {
510    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
511        write!(
512            f,
513            "({:?}, {:?})",
514            crate::tuple::Bytes::from(self.key()),
515            crate::tuple::Bytes::from(self.value())
516        )
517    }
518}
519
520impl TryFrom<FdbFutureHandle> for i64 {
521    type Error = FdbError;
522
523    fn try_from(f: FdbFutureHandle) -> FdbResult<Self> {
524        let mut version: i64 = 0;
525        error::eval(unsafe {
526            if_cfg_api_versions!(min = 620 => {
527                fdb_sys::fdb_future_get_int64(f.as_ptr(), &mut version)
528            } else {
529                fdb_sys::fdb_future_get_version(f.as_ptr(), &mut version)
530            })
531        })?;
532        Ok(version)
533    }
534}
535
536impl TryFrom<FdbFutureHandle> for () {
537    type Error = FdbError;
538    fn try_from(_f: FdbFutureHandle) -> FdbResult<Self> {
539        Ok(())
540    }
541}
542
543#[cfg(test)]
544mod tests {
545    use super::*;
546    use std::task::{Wake, Waker};
547
548    struct Task;
549
550    impl Wake for Task {
551        fn wake(self: Arc<Self>) {}
552    }
553
554    #[test]
555    fn completion_before_registering_a_new_task_is_ready() {
556        let old_waker = Waker::from(Arc::new(Task));
557        let new_waker = Waker::from(Arc::new(Task));
558        let mut registration = None;
559        let mut callback = None;
560
561        assert!(
562            poll_ready(
563                &mut registration,
564                &Context::from_waker(&old_waker),
565                || false,
566                |waker| callback = Some(waker),
567            )
568            .is_pending()
569        );
570
571        let callback = callback.unwrap();
572        let mut ready = false;
573        assert!(
574            poll_ready(
575                &mut registration,
576                &Context::from_waker(&new_waker),
577                || {
578                    let was_ready = ready;
579                    if !ready {
580                        // Complete after observing not-ready, before registering
581                        // the new task. The one-shot callback wakes the old task.
582                        ready = true;
583                        callback.wake();
584                    }
585                    was_ready
586                },
587                |_| {},
588            )
589            .is_ready()
590        );
591    }
592}