syslog-rs 7.1.0

/*-
 * syslog-rs - a syslog client translated from libc to rust
 * 
 * Copyright 2025 Aleksandr Morozov
 * 
 * The syslog-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *
 *   2. The MIT License (MIT)
 *                     
 *   3. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

use std::{fmt, marker::PhantomData, sync::{Arc, Mutex}};

use crate::
{
    DefaultLocalSyslogDestination, LogFacility, LogStat, Priority, SyslogDestination, error::SyRes, 
    formatters::{DefaultSyslogFormatter, SyslogFormatter}, 
    sync::{LogItems, SyStream, SyStreamPri, SyStreamSyslogApi, syslog_sync_internal::SyslogSocketLockless}
};

/// A public trait which defines the public interface for the `dyn` syslog instance.
pub trait DynSyslog: Send + Sync
{
    /// Connects the current instance to the syslog server (destination).
    fn connectlog(&self) -> SyRes<()>;

    /// Sets the logmask to filter out the syslog calls.
    /// 
    /// See macroses [LOG_MASK] and [LOG_UPTO] to generate mask
    ///
    /// # Example
    ///
    /// LOG_MASK!(Priority::LOG_EMERG) | LOG_MASK!(Priority::LOG_ERROR)
    ///
    /// or
    ///
    /// ~(LOG_MASK!(Priority::LOG_INFO))
    /// LOG_UPTO!(Priority::LOG_ERROR)
    fn setlogmask(&self, logmask: i32) -> SyRes<i32>;

    /// Closes connection to the syslog server (destination).
    fn closelog(&self) -> SyRes<()>;

    /// Similar to libc, syslog() sends data to syslog server.
    /// 
    /// # Arguments
    ///
    /// * `pri` - a priority [Priority]
    ///
    /// * `fmt` - a formatter string which should be sent to syslog/file.
    /// 
    /// # Returns 
    /// 
    /// A [SyRes] is returned which may describe an error.
    fn syslog(&self, pri: Priority, fmt: String) -> SyRes<()>;

    /// This function can be used to update the facility name, for example
    /// after fork().
    /// 
    /// # Arguments
    /// 
    /// * `ident` - an [Option] optional new identity (up to 48 UTF8 chars)
    ///     If set to [Option::None] would request the program name from OS.
    fn change_identity(&self, ident: Option<&str>) -> SyRes<()>;

    /// Updates the instance's socket. `tap_data` [TapTypeData] should be of
    /// the same variant (type) as current.
    fn reconnect(&self) -> SyRes<()>;
}

/// A public trait which defines the public interface for the `dyn` syslog instance.
pub trait MutDynSyslog
{
    /// Connects the current instance to the syslog server (destination).
    fn connectlog(&mut self) -> SyRes<()>;

    /// Sets the logmask to filter out the syslog calls.
    /// 
    /// See macroses [LOG_MASK] and [LOG_UPTO] to generate mask
    ///
    /// # Example
    ///
    /// LOG_MASK!(Priority::LOG_EMERG) | LOG_MASK!(Priority::LOG_ERROR)
    ///
    /// or
    ///
    /// ~(LOG_MASK!(Priority::LOG_INFO))
    /// LOG_UPTO!(Priority::LOG_ERROR)
    fn setlogmask(&mut self, logmask: i32) -> SyRes<i32>;

    /// Closes connection to the syslog server (destination).
    fn closelog(&mut self) -> SyRes<()>;

    /// Similar to libc, syslog() sends data to syslog server.
    /// 
    /// # Arguments
    ///
    /// * `pri` - a priority [Priority]
    ///
    /// * `fmt` - a formatter string which should be sent to syslog/file.
    /// 
    /// # Returns 
    /// 
    /// A [SyRes] is returned which may describe an error.
    fn syslog(&mut self, pri: Priority, fmt: String) -> SyRes<()>;

    /// This function can be used to update the facility name, for example
    /// after fork().
    /// 
    /// # Arguments
    /// 
    /// * `ident` - an [Option] optional new identity (up to 48 UTF8 chars)
    ///     If set to [Option::None] would request the program name from OS.
    fn change_identity(&mut self, ident: Option<&str>) -> SyRes<()>;

    /// Updates the instance's socket. `tap_data` [TapTypeData] should be of
    /// the same variant (type) as current.
    fn reconnect(&mut self) -> SyRes<()>;
}

/// Exposed only to allow constraint on the generic type. Should not be implemented on the
/// user's side.
pub trait SyslogType: fmt::Debug
{
    type LockItemsBase;

    type LockItems;

    type LockStreamBase<D: SyslogDestination>;

    type LockStream<D: SyslogDestination>;

    type MoveLockType;

    fn wrap_items(items: Self::LockItemsBase) -> Self::LockItems;
    fn wrap_stream<D: SyslogDestination>(stream: Self::LockStreamBase<D>) -> Self::LockStream<D>;
}

/// A main sync syslog client instance.
/// 
/// # Generics
/// 
/// * `F` - a syslog message formatter. See dir `src/formatters` for available or define one 
///     yourself. A default is [DefaultSyslogFormatter].
/// 
/// * `D` - a destination server/file. See file `src/syslog_provider.rs` for available 
///     transports. A default is [DefaultLocalSyslogDestination].
/// 
/// * `SL` - a client type. Sets the mechanism how the resources are shared. There are 3 types
///     of syslog. See info below. Default is [SyShared].
/// 
/// # Client types
/// 
/// * [SyShared] - is a single FD descriptor which is protected by Mutex. This type can be 
///     clonned, moved between threads.
/// 
/// * [SyThreadLocal] - is a thread local/lockless type which should be used only in the 
///     single thread applications or with [std::thread_local] only! Can be enabled with
///     feature `build_with_thread_local`.
/// 
/// * [SyQueued] - is a buffering/fast type which uses a separate thread to access the 
///     socket's/file's FD. This type can be clonned, moved between threads. Can be
///     enabled with feature `build_with_queue`. Also, it can be used to use the same 
///     connection/file from async and sync code, see `examples/example_sync_async.rs`.
/// 
/// Feature `build_with_queue` without any async features uses a `crossbeam` MPSC. If
/// any feature which enables `async` i.e `build_async_tokio`, `build_async_smol`, 
/// `build_async_interface`, the MPSC provider will be switch to either Smoll's, Tokio's,
/// or which you will define.
/// 
/// # Examples
/// 
/// Full default:
/// 
/// ```ignore
/// pub static SYSLOG: LazyLock<Syslog> = LazyLock::new(|| 
/// {
///     #[cfg(target_family = "unix")]
///     let syslog_provider = 
///         SyslogLocal::new();
/// 
///     #[cfg(target_family = "windows")]   
///     let syslog_provider = 
///         WindowsEvent::new();
/// 
///     Syslog::openlog(
///         Some("example"), 
///         LogStat::LOG_CONS | LogStat::LOG_PID, 
///         LogFacility::LOG_DAEMON,
///         syslog_provider
///     )
///     .unwrap()
/// }
/// );
/// ```
/// 
/// Custom i.e queued
/// 
/// ```ignore
/// pub static SYSLOG: LazyLock<Syslog<DefaultSyslogFormatter, DefaultLocalSyslogDestination, SyQueued<DefaultQueueAdapter, DefaultSyslogFormatter, DefaultLocalSyslogDestination>>> = 
/// LazyLock::new(|| 
///     {
///         #[cfg(target_family = "unix")]
///        let syslog_provider = 
///             SyslogLocal::new();
/// 
///         #[cfg(target_family = "windows")]   
///         let syslog_provider = 
///             WindowsEvent::new();
/// 
///         Syslog
///             ::<_, _, SyQueued<DefaultQueueAdapter, _, _>>
///             ::openlog_with(
///                 Some("example_sync_queue"), 
///                 LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
///                 LogFacility::LOG_DAEMON,
///                 syslog_provider
///             )
///             .unwrap()
///     }
///  );
/// ```
/// 
#[derive(Debug)]
pub struct Syslog<F = DefaultSyslogFormatter, D = DefaultLocalSyslogDestination, SL = SyShared>
where 
    F: SyslogFormatter, 
    D: SyslogDestination,
    SL: SyslogType
{   
    /// An identification i.e program name, thread name
    log_items: SL::LockItems,

    /// A stream (unixdatagram, udp, tcp)
    stream: SL::LockStream<D>,

    _p: PhantomData<F>,

    _p_not_ss: SL::MoveLockType
}

impl Syslog
{
    /// Opens a default connection to the local syslog server with default formatter.
    /// 
    /// In order to access the syslog API, use the [SyslogApi].
    /// 
    /// # Arguments
    /// 
    /// * `ident` - A program name which will appear on the logs. If none, will be determined
    ///     automatically.
    /// 
    /// * `logstat` - [LogStat] an instance config.
    /// 
    /// * `facility` - [LogFacility] a syslog facility.
    /// 
    /// * `net_tap_prov` - a [SyslogLocal] instance with configuration.
    /// 
    /// # Returns
    /// 
    /// A [SyRes] is returned ([Result]) with: 
    /// 
    /// * [Result::Ok] - with instance
    /// 
    /// * [Result::Err] - with error description.
    pub 
    fn openlog(ident: Option<&str>, logstat: LogStat, facility: LogFacility, 
        net_tap_prov: DefaultLocalSyslogDestination) -> SyRes<Self> 
    {
        return Ok( 
            Self
            {
                log_items: 
                    <SyShared as SyslogType>
                        ::wrap_items(
                            <SyShared as SyslogType>::LockItemsBase::new(ident, 0xff, logstat, facility)
                        ),
                stream: 
                    <SyShared as SyslogType>
                        ::wrap_stream(
                            <SyShared as SyslogType>::LockStreamBase::<DefaultLocalSyslogDestination>::new(logstat, net_tap_prov)?,
                        ),
                _p: 
                    PhantomData,
                _p_not_ss: 
                    PhantomData
            }
        );
    }
}

#[cfg(feature = "build_with_thread_local")]
pub mod build_with_thread_local
{
    use super::*;

    /// A threal local syslog which is completely lockless! It can be used in signle threaded
    /// applications or with the [thread_local] functionality.
    /// 
    /// ```ignore
    /// thread_local! 
    /// {
    ///     // Could add pub to make it public to whatever Foo already is public to.
    ///     static SYSLOG: RefCell<Syslog<DefaultSyslogFormatter, SyslogLocal, SyThreadLocal>> = 
    ///         RefCell::new(
    ///             Syslog
    ///                 ::<_, _, SyThreadLocal>
    ////                ::openlog_with(Some("test"), LogStat::LOG_PID, LogFacility::LOG_DAEMON, SyslogLocal::new())
    ///                     .unwrap()
    ///         );
    /// }
    /// ```
    /// 
    /// A stream is availble via [SyStreamApi].
    /// 
    /// ```ignore
    /// let _ = write!(SYSLOG.stream(Priority::LOG_DEBUG), "test {} 123 stream test ", d);
    /// ```
    /// 
    /// The instances will be completly separated and have own FD.
    /// 
    /// # Generics
    /// 
    /// * `D` - a [SyslogDestination] instance which is either:
    ///     [SyslogLocal], [crate::syslog_provider::SyslogFile], [crate::syslog_provider::SyslogNet], 
    ///     [crate::syslog_provider::SyslogTls]. By default a `SyslogLocal` is selected.
    /// 
    /// * `F` - a [SyslogFormatter] which sets the instance which would 
    ///     format the message.
    /// 
    #[derive(Debug)]
    pub struct SyThreadLocal;

    impl SyslogType for SyThreadLocal
    {
        type LockItemsBase = LogItems;
        type LockItems = Self::LockItemsBase;

        type LockStreamBase<D: SyslogDestination> = SyslogSocketLockless<D>;
        type LockStream<D: SyslogDestination> = Self::LockStreamBase<D>;
        
        type MoveLockType = PhantomData<*const ()>;

        fn wrap_items(items: Self::LockItemsBase) -> Self::LockItems 
        {
            items
        }

        fn wrap_stream<D: SyslogDestination>(stream: Self::LockStreamBase<D>) -> Self::LockStream<D> 
        {
            stream
        }
    }

    impl<F, D> MutDynSyslog for Syslog<F, D, SyThreadLocal>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
    {
        #[inline]
        fn connectlog(&mut self) -> SyRes<()> 
        {
            self.connectlog()
        }

        #[inline]
        fn setlogmask(&mut self, logmask: i32) -> SyRes<i32> 
        {
            self.setlogmask(logmask)
        }

        #[inline]
        fn closelog(&mut self) -> SyRes<()>
        {
            self.closelog()
        }
        
        fn syslog(&mut self, pri: Priority, fmt: String) -> SyRes<()> 
        {
            self.syslog(pri, fmt.into())
        }
        
        fn change_identity(&mut self, ident: Option<&str>) -> SyRes<()> 
        {
            self.change_identity(ident)
        }
        
        fn reconnect(&mut self) -> SyRes<()> 
        {
            self.reconnect()
        }
    }

    impl<F, D> Syslog<F, D, SyThreadLocal>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
    {
        pub 
        fn make_dyn(self) -> Box<dyn MutDynSyslog>
        {
            Box::new(self)
        }

        /// Opens a default connection to the local syslog server with default formatter.
        /// 
        /// # Arguments
        /// 
        /// * `ident` - A program name which will appear on the logs. If none, will be determined
        ///     automatically.
        /// 
        /// * `logstat` - [LogStat] an instance config.
        /// 
        /// * `facility` - [LogFacility] a syslog facility.
        /// 
        /// * `net_tap_prov` - a [SyslogLocal] instance with configuration.
        /// 
        /// # Returns
        /// 
        /// A [SyRes] is returned ([Result]) with: 
        /// 
        /// * [Result::Ok] - with instance
        /// 
        /// * [Result::Err] - with error description.
        pub 
        fn openlog_with(ident: Option<&str>, logstat: LogStat, facility: LogFacility, net_tap_prov: D) -> SyRes<Self> 
        {
            return Ok(
                Self
                {
                    log_items:
                        <SyThreadLocal as SyslogType>
                            ::wrap_items(
                                <SyThreadLocal as SyslogType>::LockItems::new(ident, 0xff, logstat, facility)
                            ),
                    stream:
                        <SyThreadLocal as SyslogType>
                            ::wrap_stream(
                                <SyThreadLocal as SyslogType>::LockStream::new(logstat, net_tap_prov)?
                            ),
                    _p: 
                        PhantomData,
                    _p_not_ss: 
                        PhantomData
                }
            );
        }
    }

    impl<F, D> Syslog<F, D, SyThreadLocal>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
    {
        /// Connects the current instance to the syslog server (destination).
        #[inline]
        pub 
        fn connectlog(&mut self) -> SyRes<()>
        {
            return 
                self
                    .stream
                    .connectlog();
        }

        /// Sets the logmask to filter out the syslog calls.
        /// 
        /// See macroses [LOG_MASK] and [LOG_UPTO] to generate mask
        ///
        /// # Example
        ///
        /// LOG_MASK!(Priority::LOG_EMERG) | LOG_MASK!(Priority::LOG_ERROR)
        ///
        /// or
        ///
        /// ~(LOG_MASK!(Priority::LOG_INFO))
        /// LOG_UPTO!(Priority::LOG_ERROR)
        #[inline]
        pub 
        fn setlogmask(&mut self, logmask: i32) -> SyRes<i32>
        {
            return Ok(
                self
                    .log_items
                    .set_logmask(logmask)
            );
        }

        /// Closes connection to the syslog server (destination).
        #[inline]
        pub 
        fn closelog(&mut self) -> SyRes<()> 
        {
            return 
                self
                    .stream
                    .disconnectlog();
        }

        /// Similar to libc, syslog() sends data to syslog server.
        /// 
        /// # Arguments
        ///
        /// * `pri` - a priority [Priority]
        ///
        /// * `fmt` - a formatter [SyslogFormatter] message. In C exists a functions with
        ///     variable argumets amount. In Rust you should create your
        ///     own macros like format!() or use format!()]. The [String] and ref `'static` 
        ///     [str] can be passed directly.
        /// 
        /// # Returns 
        /// 
        /// A [SyRes] is returned which may describe an error.
        #[inline]
        pub 
        fn syslog(&mut self, pri: Priority, fmt: F) -> SyRes<()>
        {
            let Some((formatted_msg, logstat)) = 
                self.log_items.vsyslog1_msg::<F, D>(pri, &fmt)
                else { return Ok(()) };

            self.stream.vsyslog1(logstat, formatted_msg)
        }

        /// This function can be used to update the facility name, for example
        /// after fork().
        /// 
        /// # Arguments
        /// 
        /// * `ident` - an [Option] optional new identity (up to 48 UTF8 chars)
        ///     If set to [Option::None] would request the program name from OS.
        #[inline]
        pub 
        fn change_identity(&mut self, ident: Option<&str>) -> SyRes<()>
        {
            self.log_items.set_identity(ident);

            return Ok(());
        }

        /// Re-opens the connection to the syslog server. Can be used to 
        /// rotate logs(handle SIGHUP).
        /// 
        /// # Returns
        /// 
        /// A [Result] is retured as [SyRes].
        /// 
        /// * [Result::Ok] - with empty inner type.
        /// 
        /// * [Result::Err] - an error code and description 
        #[inline]
        pub 
        fn reconnect(&mut self) -> SyRes<()>
        {
            return
                self
                    .stream
                    .reconnectlog();
        }

        /// Updates the instance's socket. `tap_data` [TapTypeData] should be of
        /// the same variant (type) as current.
        #[inline]
        pub 
        fn update_tap_data(&mut self, tap_data: D) -> SyRes<()>
        {
            return 
                self
                    .stream
                    .update_tap_data(tap_data.clone());
        }
    }

    impl<F, D> Syslog<F, D, SyThreadLocal>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
    {
        /// Returns the streamable [SyStream] instance which can be used with [write!].
        /// 
        /// It implements both [std::fmt::Write] and [std::io::Write].
        /// 
        /// # Example
        /// 
        /// ```ignore
        /// let log = 
        ///     SingleSyslog::openlog(
        ///         Some("test1"), 
        ///         LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
        ///         LogFacility::LOG_DAEMON,
        ///         SyslogLocal::new()
        ///     ).unwrap();
        /// 
        /// write!(log.get_stream::<SyStreamPriDebug>(), "test stream singlesyslog {}", i).unwrap();
        /// ```
        pub 
        fn get_stream<'t, PRI>(&'t mut self) -> SyStream<'t, PRI, D, F, &'t mut Self>
        where PRI: SyStreamPri
        {
            SyStream
            {
                s: Some(self),
                _p: PhantomData,
                _p1: PhantomData,
                _p2: PhantomData
            }
        }
    }

    impl<F, D> SyStreamSyslogApi<F, D>  
    for &mut Syslog<F, D, SyThreadLocal>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
    {
        type SYSLOG<'t> = &'t mut Syslog<F, D, SyThreadLocal>;

        fn syslog<'t>(syslog: Self::SYSLOG<'t>, pri: Priority, fmt: F) -> SyRes<()>
        {
            syslog.syslog(pri, fmt)
        }
    }
}

#[cfg(feature = "build_with_thread_local")]
pub use self::build_with_thread_local::SyThreadLocal;

// ---- SYSLOG SHARED

/// A `sync`, shared instance of the syslog client which is shared between many
/// threads. Previously a mutex was used, but since the v5.0.0 a CoW experimental
/// approach is used. The `CoW` creates clones of the instance without holding
/// a long mutex locks. When writing, the instance does not hold a long lock on
/// updated item. Only exclusive lock locks the readers, because the instance is
/// updated and not usable anyway.
/// 
/// If the program has fixed amount of threads, probably the `syslog_threadlocal`
/// will be better alternative. It has the same functionality, but avoids 
/// any sync locks by working in current thread.
/// 
/// # Traits
/// 
/// For this isntance a [SyslogApi] and [SyStreamApi] are implemented.
/// 
/// # Examples
/// 
/// ```ignore
/// let log = 
///     Syslog::openlog(
///         Some("test1"), 
///         LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
///         LogFacility::LOG_DAEMON,
///         SyslogLocal::new()
///     );
/// ```
/// 
/// ```ignore
/// let log = 
///     Syslog
///         ::<DefaultSyslogFormatter, SyslogLocal, SyShared>
///         ::openlog_with(
///             Some("test1"), 
///             LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
///             LogFacility::LOG_DAEMON,
///             SyslogLocal::new()
///         );
/// ```
/// 
/// ```ignore
/// pub static SYSLOG3: LazyLock<Syslog<DefaultSyslogFormatter, SyslogLocal, SyShared>> = 
///     LazyLock::new(|| 
///         {
///             Syslog
///                 ::<DefaultSyslogFormatter, SyslogLocal, SyShared>
///                 ::openlog_with(
///                     Some("test1"), 
///                     LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
///                     LogFacility::LOG_DAEMON,
///                     SyslogLocal::new()
///                 )
///                 .unwrap()
///         }
///     );
/// ```
/// # Streaming
/// 
/// A stream is availble via [SyStreamApi].
/// 
/// ```ignore
/// let _ = write!(SYSLOG.stream(Priority::LOG_DEBUG), "test {} 123 stream test ", d);
/// ```
/// 
/// # Generics
/// 
/// * `F` - a [SyslogFormatter] which sets the instance which would 
///     format the message.
/// 
/// * `D` - a [SyslogDestination] instance which is either:
///     [SyslogLocal], [SyslogFile], [SyslogNet], [SyslogTls]. By
///     default a `SyslogLocal` is selected.
#[derive(Debug)]
pub struct SyShared;

impl SyslogType for SyShared
{
    type LockItemsBase = LogItems;
    type LockItems = Arc<Mutex<Self::LockItemsBase>>;

    type LockStreamBase<D: SyslogDestination> = SyslogSocketLockless<D>;
    type LockStream<D: SyslogDestination> = Arc<Mutex<Self::LockStreamBase<D>>>;

    type MoveLockType = PhantomData<()>;

    fn wrap_items(items: Self::LockItemsBase) -> Self::LockItems 
    {
        Arc::new(Mutex::new(items))
    }

    fn wrap_stream<D: SyslogDestination>(stream: Self::LockStreamBase<D>) -> Self::LockStream<D> 
    {
        Arc::new(Mutex::new(stream))
    }
}

impl<F, D> Clone for Syslog<F, D, SyShared>
where 
    F: SyslogFormatter,
    D: SyslogDestination,
{
    fn clone(&self) -> Self 
    {
        Self 
        { 
            log_items: 
                self.log_items.clone(), 
            stream: 
                self.stream.clone(), 
            _p: 
                PhantomData, 
            _p_not_ss: 
                PhantomData,
        }
    }
}

impl<F, D> DynSyslog for Syslog<F, D, SyShared>
where 
    F: SyslogFormatter,
    D: SyslogDestination,
{
    #[inline]
    fn connectlog(&self) -> SyRes<()> 
    {
        self.connectlog()
    }

    #[inline]
    fn setlogmask(&self, logmask: i32) -> SyRes<i32> 
    {
        self.setlogmask(logmask)
    }

    #[inline]
    fn closelog(&self) -> SyRes<()>
    {
        self.closelog()
    }
    
    fn syslog(&self, pri: Priority, fmt: String) -> SyRes<()> 
    {
        self.syslog(pri, fmt.into())
    }
    
    fn change_identity(&self, ident: Option<&str>) -> SyRes<()> 
    {
        self.change_identity(ident)
    }
    
    fn reconnect(&self) -> SyRes<()> 
    {
        self.reconnect()
    }
}


impl<F, D> Syslog<F, D, SyShared>
where 
    F: SyslogFormatter,
    D: SyslogDestination,
{
    pub 
    fn make_dyn(self) -> Box<dyn DynSyslog + Send + Sync>
    {
        Box::new(self)
    }

    /// Opens a special connection to the destination syslog server with specific formatter.
    /// 
    /// All struct generic should be specified before calling this function.
    /// 
    /// In order to access the syslog API, use the [SyslogApi].
    /// 
    /// # Arguments
    /// 
    /// * `ident` - A program name which will appear on the logs. If none, will be determined
    ///     automatically.
    /// 
    /// * `logstat` - [LogStat] an instance config.
    /// 
    /// * `facility` - [LogFacility] a syslog facility.
    /// 
    /// * `net_tap_prov` - a destination server. A specific `D` instance which contains infomation 
    ///     about the destination server. See `syslog_provider.rs`.
    /// 
    /// # Returns
    /// 
    /// A [SyRes] is returned ([Result]) with: 
    /// 
    /// * [Result::Ok] - with instance
    /// 
    /// * [Result::Err] - with error description.
    pub 
    fn openlog_with(ident: Option<&str>, logstat: LogStat, facility: LogFacility, net_tap_prov: D) -> SyRes<Self> 
    {
        return Ok( 
            Self
            {
                log_items: 
                    <SyShared as SyslogType>
                        ::wrap_items(
                            <SyShared as SyslogType>::LockItemsBase::new(ident, 0xff, logstat, facility)
                        ),
                stream: 
                    <SyShared as SyslogType>
                        ::wrap_stream(
                            <SyShared as SyslogType>::LockStreamBase::<D>::new(logstat, net_tap_prov)?,
                        ),
                _p: 
                    PhantomData,
                _p_not_ss:
                    PhantomData
            }
        );
    }

    /// Just initializes the instance from other instance. For example, in the crate which uses
    /// this type of logging. 
    /// 
    /// Will work only if `F` and `D` are same.
    pub 
    fn attach(other: &Syslog<F, D, SyShared>) -> SyRes<Self>
    {
        Ok(other.clone())
    }
}

impl<F, D> Syslog<F, D, SyShared>
where 
    F: SyslogFormatter,
    D: SyslogDestination,
{
    /// Connects the current instance to the syslog server (destination).
    pub 
    fn connectlog(&self) -> SyRes<()>
    {
        return 
            self
                .stream
                .lock()
                .unwrap()
                .connectlog();
    }

    /// Sets the logmask to filter out the syslog calls.
    /// 
    /// See macroses [LOG_MASK] and [LOG_UPTO] to generate mask
    ///
    /// # Example
    ///
    /// LOG_MASK!(Priority::LOG_EMERG) | LOG_MASK!(Priority::LOG_ERROR)
    ///
    /// or
    ///
    /// ~(LOG_MASK!(Priority::LOG_INFO))
    /// LOG_UPTO!(Priority::LOG_ERROR)
    pub 
    fn setlogmask(&self, logmask: i32) -> SyRes<i32> 
    {
        let pri = 
            self
                .log_items
                .lock()
                .unwrap()
                .set_logmask(logmask);

        return Ok(pri);
    }

    /// Closes connection to the syslog server (destination).
    pub 
    fn closelog(&self) -> SyRes<()> 
    {
        return 
            self
                .stream
                .lock()
                .unwrap()
                .disconnectlog();
    }

    /// Similar to libc, syslog() sends data to syslog server.
    /// 
    /// # Arguments
    ///
    /// * `pri` - a priority [Priority]
    ///
    /// * `fmt` - a formatter [SyslogFormatter] message. In C exists a functions with
    ///     variable argumets amount. In Rust you should create your
    ///     own macros like format!() or use format!()]. The [String] and ref `'static` 
    ///     [str] can be passed directly.
    /// 
    /// # Returns 
    /// 
    /// A [SyRes] is returned which may describe an error.
    #[inline]
    pub 
    fn syslog(&self, pri: Priority, fmt: F) -> SyRes<()>
    {
        let Some((formatted_msg, logstat)) = 
            self.log_items.lock().unwrap().vsyslog1_msg::<F, D>(pri, &fmt)
        else { return Ok(()) };

        self.stream.lock().unwrap().vsyslog1(logstat, formatted_msg)
    }

    /// This function can be used to update the facility name, for example
    /// after fork().
    /// 
    /// # Arguments
    /// 
    /// * `ident` - an [Option] optional new identity (up to 48 UTF8 chars)
    ///     If set to [Option::None] would request the program name from OS.
    pub 
    fn change_identity(&self, ident: Option<&str>) -> SyRes<()>
    {
        self
            .log_items
            .lock()
            .unwrap()
            .set_identity(ident);

        return Ok(());
    }

    /// Re-opens the connection to the syslog server. Can be used to 
    /// rotate logs(handle SIGHUP).
    /// 
    /// # Returns
    /// 
    /// A [Result] is retured as [SyRes].
    /// 
    /// * [Result::Ok] - with empty inner type.
    /// 
    /// * [Result::Err] - an error code and description 
    pub 
    fn reconnect(&self) -> SyRes<()>
    {
        return
            self
                .stream
                .lock()
                .unwrap()
                .reconnectlog();
    }

    /// Updates the instance's socket. `tap_data` [TapTypeData] should be of
    /// the same variant (type) as current.
    pub 
    fn update_tap_data(&self, tap_data: D) -> SyRes<()>
    {
        return
            self
                .stream
                .lock()
                .unwrap()
                .update_tap_data(tap_data);
    }
}

impl<F, D> Syslog<F, D, SyShared>
where 
    F: SyslogFormatter,
    D: SyslogDestination,
{
    /// Returns the streamable [SyStream] instance which can be used with [write!].
    /// 
    /// It implements both [std::fmt::Write] and [std::io::Write].
    /// 
    /// # Example
    /// 
    /// ```ignore
    /// let log = 
    ///     SingleSyslog::openlog(
    ///         Some("test1"), 
    ///         LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
    ///         LogFacility::LOG_DAEMON,
    ///         SyslogLocal::new()
    ///     ).unwrap();
    /// 
    /// write!(log.get_stream::<SyStreamPriDebug>(), "test stream singlesyslog {}", i).unwrap();
    /// ```
    pub 
    fn get_stream<'t, PRI>(&'t self) -> SyStream<'t, PRI, D, F, &'t Self>
    where PRI: SyStreamPri
    {
        SyStream
        {
            s: Some(self),
            _p: PhantomData,
            _p1: PhantomData,
            _p2: PhantomData
        }
    }
}

impl<F: SyslogFormatter, D: SyslogDestination> SyStreamSyslogApi<F, D>  
for &Syslog<F, D, SyShared>
{
    type SYSLOG<'t> = &'t Syslog<F, D, SyShared>;

    fn syslog<'t>(syslog: Self::SYSLOG<'t>, pri: Priority, fmt: F) -> SyRes<()>
    {
        syslog.syslog(pri, fmt)
    }
}

// --- QUEUE


#[cfg(feature = "build_with_queue")]
pub mod build_with_queue
{
    use std::{sync::{Arc, Mutex, Weak, atomic::{AtomicBool, Ordering}}, thread};

    use crate::{DefaultLocalSyslogDestination, SyslogDestination, formatters::{DefaultSyslogFormatter, SyslogFormatter}, map_error, sy_sync_queue::{SyCmd, SyslogInternal, SyslogQueueChanSnd, SyslogQueueChannel, SyslogQueueOneChanRcv}, sync::DefaultQueueAdapter};

    use super::*;

    /// A queued syslog client which uses a separate thread to send messages to upstream.
    /// 
    /// # Generics
    /// 
    /// * `F` - a syslog message formatter. See dir `src/formatters` for available or define one 
    ///     yourself. A default is [DefaultSyslogFormatter].
    /// 
    /// * `D` - a destination server/file. See file `src/syslog_provider.rs` for available 
    ///     transports. A default is [DefaultLocalSyslogDestination].
    /// 
    /// * `S` - a queue mechanism. A default is [DefaultLocalSyslogDestination]. If you don't
    ///     need any special queue mechanism, use the default.
    #[derive(Debug, Clone)]
    pub struct SyQueued<S = DefaultQueueAdapter, F = DefaultSyslogFormatter, D = DefaultLocalSyslogDestination>
    where 
        F: SyslogFormatter, 
        D: SyslogDestination,
        S: SyslogQueueChannel<F, D>,

    {
        /// Control flag
        run_control: Weak<AtomicBool>,

        /// commands channel
        pub(crate) tasks: S::ChannelSnd,

        /// process thread
        thread: Arc<Mutex<Option<thread::JoinHandle<()>>>>,
    }

    impl<F, DD, S> SyslogType for SyQueued<S, F, DD>
    where F: SyslogFormatter, DD: SyslogDestination, S: SyslogQueueChannel<F, DD>
    {
        type LockItemsBase = ();
        type LockItems = Self::LockItemsBase;

        type LockStreamBase<D: SyslogDestination> = SyQueued<S, F, DD>;
        type LockStream<D: SyslogDestination> = Self::LockStreamBase<D>;

        type MoveLockType = PhantomData<()>;

        fn wrap_items(items: Self::LockItemsBase) -> Self::LockItems 
        {
            items
        }

        fn wrap_stream<D: SyslogDestination>(stream: Self::LockStreamBase<D>) -> Self::LockStream<D> 
        {
            stream
        }
    }

    unsafe impl<F, D, S> Send for SyQueued<S, F, D> 
    where F: SyslogFormatter, D: SyslogDestination, S: SyslogQueueChannel<F, D>
    {}

    impl<F, D, S> Drop for SyQueued<S, F, D>
    where F: SyslogFormatter, D: SyslogDestination, S: SyslogQueueChannel<F, D>
    {
        fn drop(&mut self) 
        {
            if let Some(ctrl) = self.run_control.upgrade()
            {   
                ctrl.store(false, Ordering::SeqCst);

                if let Err(_e) = self.tasks.q_send_blocking(SyCmd::form_stop())
                {

                }

                let join_handle = self.thread.lock().unwrap().take().unwrap();

                let _ = join_handle.join();
            }
        }
    }

    impl<F, D, S> Clone for Syslog<F, D, SyQueued<S, F, D>>
    where F: SyslogFormatter, D: SyslogDestination, S: SyslogQueueChannel<F, D>
    {
        fn clone(&self) -> Self 
        {
            Self 
            { 
                log_items: 
                    self.log_items.clone(), 
                stream: 
                    self.stream.clone(), 
                _p: 
                    PhantomData, 
                _p_not_ss: 
                    PhantomData
            }
        }
    }

    impl<F, D, S> DynSyslog for Syslog<F, D, SyQueued<S, F, D>>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
        S: SyslogQueueChannel<F, D>
    {
        #[inline]
        fn connectlog(&self) -> SyRes<()> 
        {
            self.connectlog()
        }

        #[inline]
        fn setlogmask(&self, logmask: i32) -> SyRes<i32> 
        {
            self.setlogmask(logmask)
        }

        #[inline]
        fn closelog(&self) -> SyRes<()>
        {
            self.closelog()
        }
        
        fn syslog(&self, pri: Priority, fmt: String) -> SyRes<()> 
        {
            self.syslog(pri, fmt.into())
        }
        
        fn change_identity(&self, ident: Option<&str>) -> SyRes<()> 
        {
            self.change_identity(ident)
        }
        
        fn reconnect(&self) -> SyRes<()> 
        {
            self.reconnect()
        }
    }

    impl<F, D, S> Syslog<F, D, SyQueued<S, F, D>>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
        S: SyslogQueueChannel<F, D>
    {
        /// Converts the current instance into dyncamic object. See [DynSyslog] for the interface.
        pub 
        fn make_dyn(self) -> Box<dyn DynSyslog + Send + Sync>
        {
            Box::new(self)
        }

        /// Opens a default connection to the local syslog server with default formatter with
        /// provided generics.
        /// 
        /// # Arguments
        /// 
        /// * `ident` - A program name which will appear on the logs. If none, will be determined
        ///     automatically.
        /// 
        /// * `logstat` - [LogStat] an instance config.
        /// 
        /// * `facility` - [LogFacility] a syslog facility.
        /// 
        /// * `net_tap_prov` - a [SyslogLocal] instance with configuration.
        /// 
        /// # Returns
        /// 
        /// A [SyRes] is returned ([Result]) with: 
        /// 
        /// * [Result::Ok] - with instance
        /// 
        /// * [Result::Err] - with error description.
        pub 
        fn openlog_with(ident: Option<&str>, logstat: LogStat, facility: LogFacility, net_tap_prov: D) -> SyRes<Self>
        {
            // creating internal syslog struct

            let log_items = 
                LogItems::new(ident, 0xff, logstat, facility);

            let stream = 
                SyslogSocketLockless::<D>::new(logstat, net_tap_prov)?;

            let (inst, sender, run_ctrl) = 
                SyslogInternal::<F, D, S>::new(log_items, stream)?;
            
            
            let thr_name: String = "syslog_queue/0".into();

            // initiate a thread
            let thread_hnd = 
                thread::Builder::new()
                    .name(thr_name.clone())
                    .spawn(move || SyslogInternal::<F, D, S>::thread_worker(inst))
                    .map_err(|e| 
                        map_error!("{} thread spawn failed. {}", thr_name, e)
                    )?;

            let sy_q = 
                SyQueued
                {
                    run_control: 
                        run_ctrl,
                    tasks: 
                        sender,
                    thread: 
                        Arc::new(Mutex::new(Some(thread_hnd))),
                };
            
            return Ok( 
                Self
                {
                    log_items: 
                        (),
                    stream: 
                        sy_q,
                    _p: 
                        PhantomData,
                    _p_not_ss:
                        PhantomData
                }
            );
        }
    }

    impl<F, D, S> Syslog<F, D, SyQueued<S, F, D>>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
        S: SyslogQueueChannel<F, D>
    {
        /// Connects the current instance to the syslog server (destination).
        pub 
        fn connectlog(&self) -> SyRes<()>
        {
            let (sy_cmd, loopback) = 
                SyCmd::form_connectlog();

            self.stream.tasks.q_send_blocking(sy_cmd)?;

            return 
                loopback
                    .recv_once_blocking()?;
        }

        /// Sets the logmask to filter out the syslog calls.
        /// 
        /// See macroses [LOG_MASK] and [LOG_UPTO] to generate mask
        ///
        /// # Example
        ///
        /// LOG_MASK!(Priority::LOG_EMERG) | LOG_MASK!(Priority::LOG_ERROR)
        ///
        /// or
        ///
        /// ~(LOG_MASK!(Priority::LOG_INFO))
        /// LOG_UPTO!(Priority::LOG_ERROR)
        pub 
        fn setlogmask(&self, logmask: i32) -> SyRes<i32> 
        {
            let (sy_cmd, loopback) = 
                SyCmd::form_logmask(logmask);

            self.stream.tasks.q_send_blocking(sy_cmd)?;

            return 
                loopback
                    .recv_once_blocking();
        }

        /// Closes connection to the syslog server (destination).
        pub 
        fn closelog(&self) -> SyRes<()> 
        {
            let (sy_cmd, loopback) = 
                SyCmd::form_disconnectlog();

            // send stop
            self.stream.tasks.q_send_blocking(sy_cmd)?;

            return 
                loopback
                    .recv_once_blocking()?;
        }

        /// Similar to libc, syslog() sends data to syslog server.
        /// 
        /// # Arguments
        ///
        /// * `pri` - a priority [Priority]
        ///
        /// * `fmt` - a formatter [SyslogFormatter] message. In C exists a functions with
        ///     variable argumets amount. In Rust you should create your
        ///     own macros like format!() or use format!()]. The [String] and ref `'static` 
        ///     [str] can be passed directly.
        /// 
        /// # Returns 
        /// 
        /// A [SyRes] is returned which may describe an error.
        pub 
        fn syslog(&self, pri: Priority, fmt: F) -> SyRes<()>
        {
            // even if the thread is in a process of termination, there is
            // no need to sync access to the run_control field as even if
            // syslog thread will terminate before someone push something on the
            // queue, it will be left in the queue until the end of program's time.
            
            let sy_cmd = SyCmd::form_syslog(pri, fmt);

            return self.stream.tasks.q_send_blocking(sy_cmd);
        }

        /// This function can be used to update the facility name, for example
        /// after fork().
        /// 
        /// # Arguments
        /// 
        /// * `ident` - an [Option] optional new identity (up to 48 UTF8 chars)
        ///     If set to [Option::None] would request the program name from OS.
        pub 
        fn change_identity(&self, ident: Option<&str>) -> SyRes<()>
        {
            let sy_cmd = 
                SyCmd::form_change_ident(ident.map(|v| v.to_string()));

            return 
                self.stream.tasks.q_send_blocking(sy_cmd);
        }

        /// Re-opens the connection to the syslog server. Can be used to 
        /// rotate logs(handle SIGHUP).
        /// 
        /// # Returns
        /// 
        /// A [Result] is retured as [SyRes].
        /// 
        /// * [Result::Ok] - with empty inner type.
        /// 
        /// * [Result::Err] - an error code and description 
        pub 
        fn reconnect(&self) -> SyRes<()>
        {
            return 
                self.stream.tasks.q_send_blocking(SyCmd::form_reconnect());
        }

        /// Updates the instance's socket. `tap_data` [TapTypeData] should be of
        /// the same variant (type) as current.
        pub 
        fn update_tap_data(&self, tap_data: D) -> SyRes<()>
        {
            let (tap_data_cmd, loopback) = SyCmd::form_update_tap(tap_data);

            self.stream.tasks.q_send_blocking(tap_data_cmd)?;

            return 
                loopback
                    .recv_once_blocking()?;
        }
    }

    impl<F, D, S> Syslog<F, D, SyQueued<S, F, D>>
    where 
        F: SyslogFormatter,
        D: SyslogDestination,
        S: SyslogQueueChannel<F, D>
    {
        /// Returns the streamable [SyStream] instance which can be used with [write!].
        /// 
        /// It implements both [std::fmt::Write] and [std::io::Write].
        /// 
        /// # Example
        /// 
        /// ```ignore
        /// let log = 
        ///     SingleSyslog::openlog(
        ///         Some("test1"), 
        ///         LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
        ///         LogFacility::LOG_DAEMON,
        ///         SyslogLocal::new()
        ///     ).unwrap();
        /// 
        /// write!(log.get_stream::<SyStreamPriDebug>(), "test stream singlesyslog {}", i).unwrap();
        /// ```
        pub 
        fn get_stream<'t, PRI>(&'t self) -> SyStream<'t, PRI, D, F, &'t Self>
        where PRI: SyStreamPri
        {
            SyStream
            {
                s: Some(self),
                _p: PhantomData,
                _p1: PhantomData,
                _p2: PhantomData
            }
        }
    }

    impl<F, D, S> SyStreamSyslogApi<F, D>  
    for &Syslog<F, D, SyQueued<S, F, D>>
    where F: SyslogFormatter, D: SyslogDestination, S: SyslogQueueChannel<F, D>
    {
        type SYSLOG<'t> = &'t Syslog<F, D, SyQueued<S, F, D>>;

        fn syslog<'t>(syslog: Self::SYSLOG<'t>, pri: Priority, fmt: F) -> SyRes<()>
        {
            syslog.syslog(pri, fmt)
        }
    }


    /// A queued implementation for ASYNC.
    #[cfg(feature = "async_enabled")]
    pub mod syslog_async_queue
    {
        use crate::error::SyRes;
        use crate::sy_sync_queue::{SyCmd, SyslogQueueChanSnd, SyslogQueueChannel, SyslogQueueOneChanRcv};
        use crate::{Priority, Syslog};
        use crate::{formatters::SyslogFormatter, SyslogDestination, SyQueued};
        use crate::a_sync::syslog_trait::AsyncSyslogQueueApi;

        impl<F: SyslogFormatter, D: SyslogDestination, S: SyslogQueueChannel<F, D>> AsyncSyslogQueueApi<F, D> 
        for Syslog<F, D, SyQueued<S, F, D>>
        {
            async 
            fn a_connectlog(&mut self) -> SyRes<()> 
            {
                let (sy_cmd, loopback) = 
                    SyCmd::form_connectlog();

                self.stream.tasks.q_send(sy_cmd).await?;

                return 
                    loopback
                        .recv_once()
                        .await?;
            }

            /// Sets the logmask to filter out the syslog calls. This function behaves 
            /// differently as it behaves in syslog_sync.rs or syslog_async.rs.
            /// It may return an error if: syslog thread had exit and some thread calls
            /// this function. Or something happened with channel. 
            /// This function blocks until the previous mask is received.
            /// 
            /// See macroses [LOG_MASK] and [LOG_UPTO] to generate mask
            ///
            /// # Example
            ///
            /// LOG_MASK!(Priority::LOG_EMERG) | LOG_MASK!(Priority::LOG_ERROR)
            ///
            /// or
            ///
            /// ~(LOG_MASK!(Priority::LOG_INFO))
            /// LOG_UPTO!(Priority::LOG_ERROR) 
            async 
            fn a_setlogmask(&self, logmask: i32) -> SyRes<i32>
            {
                let (sy_cmd, loopback) = 
                    SyCmd::form_logmask(logmask);

                self.stream.tasks.q_send(sy_cmd).await?;

                return 
                    loopback
                        .recv_once()
                        .await;
            }

            /// Closes connection to the syslog server
            async 
            fn a_closelog(&self) -> SyRes<()>
            {
                let (sy_cmd, loopback) = 
                    SyCmd::form_disconnectlog();

                // send stop
                self.stream.tasks.q_send(sy_cmd).await?;

                return 
                    loopback
                        .recv_once()
                        .await?;
            }

            /// Similar to libc, syslog() sends data to syslog server, but asynchroniously.
            /// 
            /// # Arguments
            ///
            /// * `pri` - a priority [Priority]
            ///
            /// * `fmt` - a program's message to be sent as payload. The message is encoded with the
            ///     [SyslogFormatter] and may be different for different formatters.
            #[inline]
            async 
            fn a_syslog(&self, pri: Priority, fmt: F) -> SyRes<()>
            {
                let sy_cmd = SyCmd::form_syslog(pri, fmt);

                return self.stream.tasks.q_send(sy_cmd).await;
            }


            /// Performs the reconnection to the syslog server or file re-open.
            /// 
            /// # Returns
            /// 
            /// A [Result] is retured as [SyRes].
            /// 
            /// * [Result::Ok] - with empty inner type.
            /// 
            /// * [Result::Err] - an error code and description
            async 
            fn a_reconnect(&self) -> SyRes<()>
            {
                return 
                    self.stream.tasks.q_send(SyCmd::form_reconnect()).await;
            }

            async 
            fn a_change_identity(&self, ident: &str) -> SyRes<()> 
            {
                let sy_cmd = 
                    SyCmd::form_change_ident(Some(ident.to_string()));

                return 
                    self.stream.tasks.q_send(sy_cmd).await;
            }

            /// Updates the inner instance destionation i.e path to file
            /// or server address. The type of destination can not be changed.
            /// 
            /// This function disconnects from syslog server if previously was 
            /// connected (and reconnects if was connected previously).
            /// 
            /// # Arguments 
            /// 
            /// * `new_tap` - a consumed instance of type `D` [SyslogDestination]
            /// 
            /// # Returns 
            /// 
            /// A [SyRes] is returned. An error may be returned if:
            /// 
            /// * connection to server was failed
            /// 
            /// * incorrect type
            /// 
            /// * disconnect frm server failed
            async 
            fn a_update_tap_data(&self, new_tap: D) -> SyRes<()>
            {
                let (tap_data_cmd, loopback) = SyCmd::form_update_tap(new_tap);

                self.stream.tasks.q_send(tap_data_cmd).await?;

                return 
                    loopback
                        .recv_once()
                        .await?;
            }
        }
    }
}

#[cfg(feature = "build_with_queue")]
pub use self::build_with_queue::SyQueued;