From 4f28aa01a283a2b5d156c02f4a1f303b557d2009 Mon Sep 17 00:00:00 2001 From: Dmitriy Pleshevskiy Date: Sun, 17 Oct 2021 23:12:55 +0300 Subject: [PATCH] doc: add documentation --- Cargo.lock | 2 +- Cargo.toml | 2 +- src/asyn.rs | 37 +++++++++++++++++++++++++++++++++++++ src/bb8_postgres.rs | 13 +++++++++++++ src/r2d2_postgres.rs | 13 +++++++++++++ src/syn.rs | 37 +++++++++++++++++++++++++++++++++++++ 6 files changed, 102 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index a770c08..3b3e1a3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -493,7 +493,7 @@ checksum = "692fcb63b64b1758029e0a96ee63e049ce8c5948587f2f7208df04625e5f6b56" [[package]] name = "ood_persistence" -version = "0.2.0" +version = "0.2.1" dependencies = [ "async-trait", "bb8", diff --git a/Cargo.toml b/Cargo.toml index 11e1cd3..1e7c4ad 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "ood_persistence" -version = "0.2.0" +version = "0.2.1" edition = "2018" authors = ["Dmitriy Pleshevskiy "] repository = "https://github.com/pleshevskiy/ood_persistence" diff --git a/src/asyn.rs b/src/asyn.rs index 9495ab6..b691f8c 100644 --- a/src/asyn.rs +++ b/src/asyn.rs @@ -1,29 +1,66 @@ use crate::error; +/// The pool is one of the main features to be realized in persistence. +/// +/// Any implementation (database, file storage, memory or others) must be able to get a connection +/// to manipulate it afterwards. #[async_trait] pub trait PersistencePool: Send + Sync { + /// ConnectionClient implementation that persistence can can return. type Conn: ConnectionClient; + /// Returns new connection. + /// + /// # Errors + /// + /// Returns PersistenceError if pool cannot get a connection. async fn get_connection(&self) -> error::Result; } +/// Connection client knows about the inner connection, and also knows how to create transactions. #[cfg_attr(feature = "nightly", async_trait)] pub trait ConnectionClient { + /// Inner connection type InnerConn; + /// TransactionClient implementation in which the connection can be updated. + /// + /// **Note:** requires nightly rust channel and enabling the `nightly` feature. #[cfg(feature = "nightly")] type Trx<'t>: TransactionClient; + /// Returns inner connection fn inner(&mut self) -> &mut Self::InnerConn; + /// Updates connection to transaction. + /// + /// **Note:** requires nightly rust channel and enabling the `nightly` feature. + /// + /// # Errors + /// + /// Returns PersistenceError if connection cannot update to transaction. #[cfg(feature = "nightly")] async fn start_transaction(&mut self) -> error::Result>; } +/// Transaction client is updated connection client that can additionally commit and rollback data +/// in transactions. +/// +/// **Note:** requires nightly rust channel and enabling the `nightly` feature. #[cfg(feature = "nightly")] #[async_trait] pub trait TransactionClient: ConnectionClient { + /// Consumes the transaction, committing all changes made within it. + /// + /// # Errors + /// + /// Returns PersistenceError if transaction cannot commit async fn commit(self) -> error::Result<()>; + /// Rolls the transaction back, discarding all changes made within it. + /// + /// # Errors + /// + /// Returns PersistenceError if transaction cannot rolls back. async fn rollback(self) -> error::Result<()>; } diff --git a/src/bb8_postgres.rs b/src/bb8_postgres.rs index 90a9555..90b0f43 100644 --- a/src/bb8_postgres.rs +++ b/src/bb8_postgres.rs @@ -7,15 +7,23 @@ pub use bb8::{Pool, PooledConnection}; pub use bb8_postgres::tokio_postgres; pub use bb8_postgres::PostgresConnectionManager as Manager; +/// Inner connection of bb8 implementation. pub type InnerConn<'p, M> = PooledConnection<'p, M>; +/// Inner connection of tokio postgres connection. pub type InnerTrx<'p> = tokio_postgres::Transaction<'p>; +/// Alias for bb8 postgres no tls manager. pub type NoTlsManager = Manager; +/// Alias for bb8 postgres no tls persistence. pub type NoTlsPersistence<'p> = Persistence<'p, NoTlsManager>; +/// Alias for bb8 postgres no tls connection. pub type NoTlsConnection<'p> = Connection<'p, NoTlsManager>; +/// Alias for bb8 postgres no tls inner connection. pub type NoTlsInnerConn<'p> = InnerConn<'p, NoTlsManager>; +/// Alias for bb8 postgres no tls pool. pub type NoTlsPool = Pool; +/// It creates new persistence of bb8 postgres implementation. #[must_use] pub fn new(pool: &Pool) -> Persistence where @@ -24,6 +32,7 @@ where Persistence(pool) } +/// Persistence wrap over bb8 pool. #[derive(Clone)] pub struct Persistence<'p, M>(&'p Pool) where @@ -42,6 +51,7 @@ impl<'p> PersistencePool for NoTlsPersistence<'p> { } } +/// Connection wrap over bb8 postgres inner connection. pub struct Connection<'p, M>(InnerConn<'p, M>) where M: bb8::ManageConnection; @@ -67,6 +77,9 @@ impl<'me> ConnectionClient for NoTlsConnection<'me> { } } +/// Transaction wrap over tokio_postgres transaction. +/// +/// **Note:** requires nightly rust channel and enabling the `nightly` feature. #[cfg(feature = "nightly")] pub struct Transaction<'p>(InnerTrx<'p>); diff --git a/src/r2d2_postgres.rs b/src/r2d2_postgres.rs index a81c849..a0a76e5 100644 --- a/src/r2d2_postgres.rs +++ b/src/r2d2_postgres.rs @@ -7,15 +7,23 @@ pub use r2d2::{Pool, PooledConnection}; pub use r2d2_postgres::postgres; pub use r2d2_postgres::PostgresConnectionManager as Manager; +/// Inner connection of r2d2 implementation. pub type InnerConn = PooledConnection; +/// Inner connection of postgres connection. pub type InnerTrx<'t> = postgres::Transaction<'t>; +/// Alias for r2d2 postgres no tls manager. pub type NoTlsManager = Manager; +/// Alias for r2d2 postgres no tls persistence. pub type NoTlsPersistence<'p> = Persistence<'p, NoTlsManager>; +/// Alias for r2d2 postgres no tls connection. pub type NoTlsConnection = Connection; +/// Alias for r2d2 postgres no tls inner connection. pub type NoTlsInnerConn = InnerConn; +/// Alias for r2d2 postgres no tls pool. pub type NoTlsPool = Pool; +/// It creates new persistence of r2d2 postgres implementation. pub fn new(pool: &Pool) -> Persistence where M: r2d2::ManageConnection, @@ -23,6 +31,7 @@ where Persistence(pool) } +/// Persistence wrap over r2d2 pool. #[derive(Clone)] pub struct Persistence<'p, M>(&'p Pool) where @@ -39,6 +48,7 @@ impl<'p> PersistencePool for NoTlsPersistence<'p> { } } +/// Connection wrap over r2d2 postgres inner connection. pub struct Connection(InnerConn) where M: r2d2::ManageConnection; @@ -62,6 +72,9 @@ impl ConnectionClient for NoTlsConnection { } } +/// Transaction wrap over postgres transaction. +/// +/// **Note:** requires nightly rust channel and enabling the `nightly` feature. #[cfg(feature = "nightly")] pub struct Transaction<'me>(InnerTrx<'me>); diff --git a/src/syn.rs b/src/syn.rs index f0c006c..c5e9b00 100644 --- a/src/syn.rs +++ b/src/syn.rs @@ -1,26 +1,63 @@ use crate::error; +/// The pool is one of the main features to be realized in persistence. +/// +/// Any implementation (database, file storage, memory or others) must be able to get a connection +/// to manipulate it afterwards. pub trait PersistencePool { + /// ConnectionClient implementation that persistence can can return. type Conn: ConnectionClient; + /// Returns new connection. + /// + /// # Errors + /// + /// Returns PersistenceError if pool cannot get a connection. fn get_connection(&self) -> error::Result; } +/// Connection client knows about the inner connection, and also knows how to create transactions. pub trait ConnectionClient { + /// Inner connection type InnerConn; + /// TransactionClient implementation in which the connection can be updated. + /// + /// **Note:** requires nightly rust channel and enabling the `nightly` feature. #[cfg(feature = "nightly")] type Trx<'t>: TransactionClient; + /// Returns inner connection fn inner(&mut self) -> &mut Self::InnerConn; + /// Updates connection to transaction. + /// + /// **Note:** requires nightly rust channel and enabling the `nightly` feature. + /// + /// # Errors + /// + /// Returns PersistenceError if connection cannot update to transaction. #[cfg(feature = "nightly")] fn start_transaction(&mut self) -> error::Result>; } +/// Transaction client is updated connection client that can additionally commit and rollback data +/// in transactions. +/// +/// **Note:** requires nightly rust channel and enabling the `nightly` feature. #[cfg(feature = "nightly")] pub trait TransactionClient: ConnectionClient { + /// Consumes the transaction, committing all changes made within it. + /// + /// # Errors + /// + /// Returns PersistenceError if transaction cannot commit fn commit(self) -> error::Result<()>; + /// Rolls the transaction back, discarding all changes made within it. + /// + /// # Errors + /// + /// Returns PersistenceError if transaction cannot rolls back. fn rollback(self) -> error::Result<()>; }