cdns_rs/a_sync/
interface.rs

1/*-
2 * cdns-rs - a simple sync/async DNS query library.
3 * 
4 * Copyright (C) 2020  Aleksandr Morozov
5 * 
6 * Copyright (C) 2025 Aleksandr Morozov
7 * 
8 * The syslog-rs crate can be redistributed and/or modified
9 * under the terms of either of the following licenses:
10 *
11 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
12 *                     
13 *   2. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
14 */
15
16use std::{fmt, path::Path};
17
18use crate::{a_sync::caches::CacheInstance, cfg_host_parser::HostConfig, ResolveConfig};
19
20/// This trait is a common interface for the ASYNC IO operation and syncronization.
21/// 
22/// The implentation of this trait is mandatory to provide access to the IO and 
23/// synchronization for the crate.
24pub trait MutexedCaches: fmt::Debug
25{
26    /// A type which could be used for the File IO operations. This type must implement
27    /// [UnifiedFs] which is a common interface for the required IO operations.
28    type MetadataFs: UnifiedFs;
29
30    /// An async mutex realization for the pre-specified type of [CacheInstance] [ResolveConfig].
31    /// 
32    /// This is generally a [Mutex] implementation whuch is defined in trait [AsyncMutex].
33    type ResolveCache: AsyncMutex<CacheInstance<ResolveConfig, Self::MetadataFs>> + fmt::Debug;
34
35    /// An async mutex realization for the pre-specified type of [CacheInstance] [HostConfig].
36    /// 
37    /// This is generally a [Mutex] implementation whuch is defined in trait [AsyncMutex].
38    type HostCahae: AsyncMutex<CacheInstance<HostConfig, Self::MetadataFs>> + fmt::Debug;
39}
40
41/// A trait which unifies the `file` IO operations.
42#[allow(async_fn_in_trait)]
43pub trait UnifiedFs
44{
45    /// Error type for `metadata` operation.
46    type ErrRes: fmt::Display;
47
48    /// A `file` realization struct.
49    type FileOp;
50
51    /// Get the metadata for the file specified by the argument `path`.
52    async fn metadata(path: &Path) -> Result<std::fs::Metadata, Self::ErrRes>;
53
54    /// Open the file specified by the argument `path` for reading only!
55    async fn open<P: AsRef<Path>>(path: P) -> std::io::Result<Self::FileOp>;
56
57    /// Reads from the `file` of type`Self::FileOp` into a [String] buffer a file content.
58    async fn read_to_string(file: &mut Self::FileOp, buf: &mut String) -> std::io::Result<usize>;
59}
60
61/// A trait which generalize the mutex from the std lib's of multiple async executors.
62/// The trait can be implemented on `mutex` directly or on a structure with mutex as 
63/// inner type. 
64#[allow(async_fn_in_trait)]
65pub trait AsyncMutex<DS: Sized>
66{
67    /// A mutex guard type.
68    type MutxGuard<'mux>: AsyncMutexGuard<'mux, DS> where Self: 'mux;
69
70    /// Creates new mutex instance for type which implements the [AsyncSyslogApi].
71    fn a_new(v: DS) -> Self;
72
73    /// Locks the mutex emmiting the `mutex guard`.
74    async fn a_lock<'mux>(&'mux self) -> Self::MutxGuard<'mux>;
75}
76
77/// A trait which generalize the mutex guarding emited by the mutex from various async executors.
78pub trait AsyncMutexGuard<'mux, DS: Sized>
79{
80    /// Returns the reference to the inner type of the mutex guard.
81    fn guard(&self) -> &DS;
82
83    /// Returns the mutable reference to the inner type of the mutex guard.
84    fn guard_mut(&mut self) -> &mut DS;
85}
cdns_rs/a_sync/interface.rs

cdns_rs/a_sync/
interface.rs
