rocket_community/request/
mod.rs

1//! Types and traits for request parsing and handling.
2
3mod atomic_method;
4mod from_param;
5mod from_request;
6mod request;
7
8#[cfg(test)]
9mod tests;
10
11pub use self::from_param::{FromParam, FromSegments};
12pub use self::from_request::{FromRequest, Outcome};
13pub use self::request::Request;
14
15#[doc(hidden)]
16pub use rocket_codegen::FromParam;
17
18#[doc(inline)]
19pub use crate::response::flash::FlashMessage;
20
21pub(crate) use self::atomic_method::AtomicMethod;
22pub(crate) use self::request::ConnectionMeta;
23
24crate::export! {
25    /// Store and immediately retrieve a vector-like value `$v` (`String` or
26    /// `Vec<T>`) in `$request`'s local cache using a locally generated
27    /// anonymous type to avoid type conflicts.
28    ///
29    /// Unlike `local_cache_once`, this macro's generated code _always_ returns
30    /// a unique reference to request-local cache.
31    ///
32    /// # Note
33    ///
34    /// The value `$v` must be of type `String` or `Vec<T>`, that is, a type
35    /// that implements the sealed trait [`Shareable`](crate::form::Shareable)bb).
36    ///
37    /// # Example
38    ///
39    /// ```rust
40    /// # extern crate rocket_community as rocket;
41    /// use rocket::request::{local_cache, local_cache_once};
42    /// # let c = rocket::local::blocking::Client::debug_with(vec![]).unwrap();
43    /// # let request = c.get("/");
44    ///
45    /// // The first store into local cache for a given type wins.
46    /// for i in 0..4 {
47    ///     assert_eq!(request.local_cache(|| i.to_string()), "0");
48    /// }
49    ///
50    /// // This shows that we cannot cache different values of the same type; we
51    /// // _must_ use a proxy type. To avoid the need to write these manually, use
52    /// // `local_cache!`, which generates one of the fly.
53    /// for i in 0..4 {
54    ///     assert_eq!(local_cache!(request, i.to_string()), i.to_string());
55    /// }
56    ///
57    /// // Note that while `local_cache_once!` generates a new type for the
58    /// // _macro_ invocation, that type is the same per run-time invocation, so
59    /// // all "calls" to `local_cache_once!` on the same line return the same
60    /// // reference for a given request.
61    /// for i in 1..4 {
62    ///     // Note that this is `1`, so _not_ the `String` from line 4.
63    ///     assert_eq!(local_cache_once!(request, i.to_string()), "1");
64    /// }
65    /// ```
66    macro_rules! local_cache {
67        ($request:expr, $v:expr $(,)?) => ({
68            struct Local<T: $crate::form::Shareable>($crate::form::SharedStack<T>);
69            let stack = $request.local_cache(|| Local($crate::form::SharedStack::new()));
70            stack.0.push_owned($v)
71        })
72    }
73}
74
75crate::export! {
76    /// Store and immediately retrieve a value `$v` in `$request`'s local cache
77    /// using a locally generated anonymous type to avoid type conflicts.
78    ///
79    /// The code generated by this macro is expected to be invoked at-most once
80    /// per-request. This is because while `local_cache_once!` generates a new
81    /// type for the _macro_ invocation, that type is the same per run-time
82    /// invocation. Thus, for a given request, a `local_cache_once!` invocation
83    /// always returns the same reference.
84    ///
85    /// To get a unique request-local reference to string-like values, use
86    /// [`local_cache!`] instead.
87    ///
88    /// # Example
89    ///
90    /// ```rust
91    /// # extern crate rocket_community as rocket;
92    /// use rocket::request::local_cache_once;
93    /// # let c = rocket::local::blocking::Client::debug_with(vec![]).unwrap();
94    /// # let request = c.get("/");
95    ///
96    /// // The first store into local cache for a given type wins.
97    /// assert_eq!(request.local_cache(|| String::from("hello")), "hello");
98    ///
99    /// // The following returns the cached, previously stored value for the type.
100    /// assert_eq!(request.local_cache(|| String::from("goodbye")), "hello");
101    ///
102    /// // This shows that we cannot cache different values of the same type;
103    /// // we _must_ use a proxy type. To avoid the need to write these manually,
104    /// // use `local_cache_once!`, which generates one of the fly.
105    /// assert_eq!(local_cache_once!(request, String::from("hello")), "hello");
106    /// assert_eq!(local_cache_once!(request, String::from("goodbye")), "goodbye");
107    ///
108    /// // But a macro invocation for the same request always resolves to the
109    /// // first reference as the unique type is generated at compile-time.
110    /// for i in 1..4 {
111    ///     assert_eq!(local_cache_once!(request, i.to_string()), "1");
112    /// }
113    /// ```
114    macro_rules! local_cache_once {
115        ($request:expr, $v:expr $(,)?) => ({
116            struct Local<T>(T);
117            &$request.local_cache(move || Local($v)).0
118        })
119    }
120}
rocket_community/request/mod.rs

rocket_community/request/
mod.rs
