Skip to content

Commit

Permalink
Updating docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@the10thWiz
the10thWiz committed Nov 22, 2024
1 parent 2a63797 commit aa845ad
Show file tree
Hide file tree
Showing 5 changed files with 57 additions and 169 deletions.
208 changes: 45 additions & 163 deletions contrib/sync_db_pools/lib/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -402,194 +402,76 @@ pub mod example {
/// #[database("example")]
/// pub struct ExampleDb(diesel::SqliteConnection);
/// ```
pub struct ExampleDb(crate::Connection<Self, diesel::SqliteConnection>);

pub struct ExampleDb(
#[allow(dead_code)]
crate::Connection<Self, diesel::SqliteConnection>,
);
#[allow(dead_code)]
impl ExampleDb {
/// Returns a fairing that initializes the database connection pool
/// associated with `Self`.
///
/// The fairing _must_ be attached before `Self` can be used as a
/// request guard.
///
/// # Example
///
/// ```rust
/// # #[macro_use] extern crate rocket;
/// # #[macro_use] extern crate rocket_sync_db_pools;
/// #
/// # #[cfg(feature = "diesel_sqlite_pool")] {
/// use rocket_sync_db_pools::diesel;
///
/// #[database("my_db")]
/// struct MyConn(diesel::SqliteConnection);
///
/// #[launch]
/// fn rocket() -> _ {
/// rocket::build().attach(MyConn::fairing())
/// }
/// # }
/// ```
/// Returns a fairing that initializes the database connection pool.
pub fn fairing() -> impl crate::rocket::fairing::Fairing {
<crate::ConnectionPool<Self, diesel::SqliteConnection>>::fairing(
"'example' Database Pool",
"example",
)
<crate::ConnectionPool<
Self,
diesel::SqliteConnection,
>>::fairing("'example' Database Pool", "example")
}

/// Returns an opaque type that represents the connection pool backing
/// connections of type `Self` _as long as_ the fairing returned by
/// [`Self::fairing()`] is attached and has run on `__rocket`.
///
/// The returned pool is `Clone`. Values of type `Self` can be retrieved
/// from the pool by calling `pool.get().await` which has the same
/// signature and semantics as [`Self::get_one()`].
///
/// # Example
///
/// ```rust
/// # #[macro_use] extern crate rocket;
/// # #[macro_use] extern crate rocket_sync_db_pools;
/// #
/// # #[cfg(feature = "diesel_sqlite_pool")] {
/// use rocket::tokio::{task, time};
/// use rocket::fairing::AdHoc;
/// use rocket_sync_db_pools::diesel;
///
/// #[database("my_db")]
/// struct MyConn(diesel::SqliteConnection);
///
/// #[launch]
/// fn rocket() -> _ {
/// rocket::build()
/// .attach(MyConn::fairing())
/// .attach(AdHoc::try_on_ignite("Background DB", |rocket| async {
/// let pool = match MyConn::pool(&rocket) {
/// Some(pool) => pool.clone(),
/// None => return Err(rocket)
/// };
///
/// // Start a background task that runs some database
/// // operation every 10 seconds. If a connection isn't
/// // available, retries 10 + timeout seconds later.
/// tokio::task::spawn(async move {
/// loop {
/// time::sleep(time::Duration::from_secs(10)).await;
/// if let Some(conn) = pool.get().await {
/// conn.run(|c| { /* perform db ops */ }).await;
/// }
/// }
/// });
///
/// Ok(rocket)
/// }))
/// }
/// # }
/// ```
/// Returns an opaque type that represents the connection pool
/// backing connections of type `Self`.
pub fn pool<P: crate::rocket::Phase>(
__rocket: &crate::rocket::Rocket<P>,
) -> Option<&crate::ConnectionPool<Self, diesel::SqliteConnection>>
{
<crate::ConnectionPool<Self, diesel::SqliteConnection>>::pool(
&__rocket,
)
) -> Option<
&crate::ConnectionPool<Self, diesel::SqliteConnection>,
> {
<crate::ConnectionPool<
Self,
diesel::SqliteConnection,
>>::pool(&__rocket)
}

/// Runs the provided function `__f` in an async-safe blocking thread.
/// The function is supplied with a mutable reference to the raw
/// connection (a value of type `&mut Self.0`). `.await`ing the return
/// value of this function yields the value returned by `__f`.
///
/// # Example
///
/// ```rust
/// # #[macro_use] extern crate rocket;
/// # #[macro_use] extern crate rocket_sync_db_pools;
/// #
/// # #[cfg(feature = "diesel_sqlite_pool")] {
/// use rocket_sync_db_pools::diesel;
///
/// #[database("my_db")]
/// struct MyConn(diesel::SqliteConnection);
///
/// #[get("/")]
/// async fn f(conn: MyConn) {
/// // The type annotation is illustrative and isn't required.
/// let result = conn.run(|c: &mut diesel::SqliteConnection| {
/// // Use `c`.
/// }).await;
/// }
/// # }
/// ```
/// Runs the provided function `__f` in an async-safe blocking
/// thread.
pub async fn run<F, R>(&self, __f: F) -> R
where
F: FnOnce(&mut diesel::SqliteConnection) -> R + Send + 'static,
R: Send + 'static,
{
self.0.run(__f).await
}

/// Retrieves a connection of type `Self` from the `rocket` instance.
/// Returns `Some` as long as `Self::fairing()` has been attached and
/// there is a connection available within at most `timeout` seconds.
pub async fn get_one<P: crate::rocket::Phase>(
__rocket: &crate::rocket::Rocket<P>,
) -> Option<Self> {
<crate::ConnectionPool<Self, diesel::SqliteConnection>>::get_one(
&__rocket,
)
.await
.map(Self)
<crate::ConnectionPool<
Self,
diesel::SqliteConnection,
>>::get_one(&__rocket)
.await
.map(Self)
}
}

/// Retrieves a connection from the database pool or fails with a
/// `Status::ServiceUnavailable` if doing so times out.
#[crate::rocket::async_trait]
impl<'r> crate::rocket::request::FromRequest<'r> for ExampleDb {
type Error = ();
#[allow(
clippy::let_unit_value,
clippy::no_effect_underscore_binding,
clippy::shadow_same,
clippy::type_complexity,
clippy::type_repetition_in_bounds,
clippy::used_underscore_binding
)]
fn from_request<'life0, 'async_trait>(
__r: &'r crate::rocket::request::Request<'life0>,
) -> ::core::pin::Pin<
Box<
dyn ::core::future::Future<
Output = crate::rocket::request::Outcome<Self, ()>,
> + ::core::marker::Send
+ 'async_trait,
>,
>
where
'r: 'async_trait,
'life0: 'async_trait,
Self: 'async_trait,
{
Box::pin(async move {
if let ::core::option::Option::Some(__ret) = ::core::option::Option::None::<
crate::rocket::request::Outcome<Self, ()>,
> {
return __ret;
}
let __r = __r;
let __ret: crate::rocket::request::Outcome<Self, ()> = {
< crate :: Connection < Self , diesel :: SqliteConnection > >
:: from_request (__r) . await . map (Self)
};
#[allow(unreachable_code)]
__ret
})
type Error = crate::ConnectionMissing;
async fn from_request(
__r: &'r crate::rocket::request::Request<'_>,
) -> crate::rocket::request::Outcome<Self, Self::Error> {
<crate::Connection<
Self,
diesel::SqliteConnection,
>>::from_request(__r)
.await
.map(Self)
}
}
impl crate::rocket::Sentinel for ExampleDb {
fn abort(
__r: &crate::rocket::Rocket<crate::rocket::Ignite>,
__r: &crate::rocket::Rocket<
crate::rocket::Ignite,
>,
) -> bool {
<crate::Connection<Self, diesel::SqliteConnection>>::abort(__r)
<crate::Connection<
Self,
diesel::SqliteConnection,
>>::abort(__r)
}
}
}
5 changes: 5 additions & 0 deletions core/codegen/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -313,6 +313,11 @@ route_attribute!(options => Method::Options);
/// fn default(status: Status, req: &Request) -> String {
/// format!("{} ({})", status, req.uri())
/// }
///
/// #[catch(500, error = "<e>")]
/// fn std_io_error(e: &std::io::Error) -> String {
/// format!("Std error: {:?}", e)
/// }
/// ```
///
/// # Grammar
Expand Down
4 changes: 2 additions & 2 deletions core/http/src/uri/uri.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ impl<'a> Uri<'a> {
/// // Invalid URIs fail to parse.
/// Uri::parse::<Origin>("foo bar").expect_err("invalid URI");
/// ```
pub fn parse<T>(string: &'a str) -> Result<Uri<'a>, Error<'_>>
pub fn parse<T>(string: &'a str) -> Result<Uri<'a>, Error<'a>>
where T: Into<Uri<'a>> + TryFrom<&'a str, Error = Error<'a>>
{
T::try_from(string).map(|v| v.into())
Expand Down Expand Up @@ -127,7 +127,7 @@ impl<'a> Uri<'a> {
/// let uri: Origin = uri!("/a/b/c?query");
/// let uri: Reference = uri!("/a/b/c?query#fragment");
/// ```
pub fn parse_any(string: &'a str) -> Result<Uri<'a>, Error<'_>> {
pub fn parse_any(string: &'a str) -> Result<Uri<'a>, Error<'a>> {
crate::parse::uri::from_str(string)
}

Expand Down
5 changes: 3 additions & 2 deletions core/lib/src/fairing/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,15 +163,16 @@ pub type FilterResult<'r> = std::result::Result<(), Box<dyn TypedError<'r> + 'r>
/// is called just after a request is received, immediately after
/// pre-processing the request and running all `Request` fairings. This method
/// returns a `Result`, which can be used to terminate processing of a request,
// TODO: Typed: links
/// bypassing the routing process. The error value must be a `TypedError`, which
/// bypassing the routing process. The error value must be a [`TypedError`], which
/// can then be caught by a typed catcher.
///
/// This method should only be used for global filters, i.e., filters that need
/// to be run on every (or very nearly every) route. One common example might be
/// CORS, since the CORS headers of every request need to be inspected, and potentially
/// rejected.
///
/// [`TypedError`]: crate::catcher::TypedError
///
/// * **<a name="response">Response</a> (`on_response`)**
///
/// A response callback, represented by the [`Fairing::on_response()`]
Expand Down
4 changes: 2 additions & 2 deletions core/lib/src/form/context.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ impl<'v> Context<'v> {
/// let foo_bar = form.context.field_errors("foo.bar");
/// }
/// ```
pub fn field_errors<'a, N>(&'a self, name: N) -> impl Iterator<Item = &Error<'v>> + '_
pub fn field_errors<'a, N>(&'a self, name: N) -> impl Iterator<Item = &'a Error<'v>> + 'a
where N: AsRef<Name> + 'a
{
self.errors.values()
Expand Down Expand Up @@ -267,7 +267,7 @@ impl<'v> Context<'v> {
/// let foo_bar = form.context.exact_field_errors("foo.bar");
/// }
/// ```
pub fn exact_field_errors<'a, N>(&'a self, name: N) -> impl Iterator<Item = &Error<'v>> + '_
pub fn exact_field_errors<'a, N>(&'a self, name: N) -> impl Iterator<Item = &'a Error<'v>> + 'a
where N: AsRef<Name> + 'a
{
self.errors.values()
Expand Down

0 comments on commit aa845ad

Please sign in to comment.