From f5a9f0f3c834887f3a8af36d3d51fdfb76e7d3f5 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 9 Aug 2023 14:38:14 +0200 Subject: [PATCH 01/37] feat: add docs and req-links to publisher --- src/publisher.rs | 119 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 118 insertions(+), 1 deletion(-) diff --git a/src/publisher.rs b/src/publisher.rs index 4001590..0a606d1 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -15,9 +15,23 @@ use crate::{ }; /// Trait to implement for [`Id`], to control the publisher and all listeners. +/// +/// [cap.ctrl](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrl-control-capturing) pub trait CaptureControl { + /// Returns `true` if the given [`Id`] is used to signal the start of event capturing. + /// + /// **Possible implementation:** + /// + /// ```ignore + /// id == &START_CAPTURING_ID + /// ``` + /// + /// [cap.ctrl.start] fn start(id: &Self) -> bool; + /// Returns the *start-ID*. + /// + /// [cap.ctrl.start] fn start_id() -> Self; /// Returns `true` if the given [`Id`] is used to signal the end of event capturing. @@ -27,11 +41,19 @@ pub trait CaptureControl { /// ```ignore /// id == &STOP_CAPTURING_ID /// ``` + /// + /// [cap.ctrl.stop] fn stop(id: &Self) -> bool; + /// Returns the *stop-ID*. + /// + /// [cap.ctrl.stop] fn stop_id() -> Self; } +/// Returns `true` if the given [`Id`] is used to control capturing. +/// +/// [cap.ctrl] pub fn is_control_id(id: &impl CaptureControl) -> bool { CaptureControl::stop(id) || CaptureControl::start(id) } @@ -56,10 +78,17 @@ pub enum EventTimestampKind { Created, } +// Types below used for better clarity according to clippy. + type Subscriber = HashMap>; type IdSubscriber = HashMap>; type Capturer = SyncSender>; +/// An **EvidentPublisher** is used to capture, publish, and manage subscriptions. +/// +/// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. +/// +/// [pub] pub struct EvidentPublisher where K: Id + CaptureControl, @@ -67,15 +96,48 @@ where T: EventEntry, F: Filter, { + /// The hashmap of subscribers listening to specific events. + /// + /// [subs.specific] pub(crate) subscriptions: Arc>>, + + /// The hashmap of subscribers listening to all events. + /// + /// [subs.all] pub(crate) any_event: Arc>>, + + /// The send-part of the capturing channel. + /// + /// [cap] pub(crate) capturer: Capturer, + + /// Optional filter that is applied when capturing events. + /// + /// [cap.filter] filter: Option, + + /// Flag to control if capturing is active or inactive. + /// + /// [cap.ctrl] capturing: Arc, + + /// Flag to control the capture mode. capture_blocking: Arc, + + /// Defines the size of the capturing send-buffer. + /// + /// [cap] capture_channel_bound: usize, + + /// Defines the size of each subscription send-buffer. + /// + /// [subs] subscription_channel_bound: usize, + + /// Number of missed captures in *non-blocking* capture mode. missed_captures: Arc, + + /// Defines at what point the event-timestamp is created. timestamp_kind: EventTimestampKind, } @@ -86,6 +148,9 @@ where T: EventEntry, F: Filter, { + /// Create a new [`EvidentPublisher`], and spawn a new event handler thread for events captured by the publisher. + /// + /// [pub] fn create( mut on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: Option, @@ -97,6 +162,7 @@ where let (send, recv): (SyncSender>, _) = mpsc::sync_channel(capture_channel_bound); + // [pub.threaded] thread::spawn(move || { while let Ok(mut event) = recv.recv() { if timestamp_kind == EventTimestampKind::Captured { @@ -117,6 +183,7 @@ where any_event: Arc::new(RwLock::new(HashMap::new())), capturer: send, filter, + // [cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrlinit-initial-capturing-state) capturing: Arc::new(AtomicBool::new(true)), capture_blocking: mode, capture_channel_bound, @@ -126,6 +193,9 @@ where } } + /// Create a new [`EvidentPublisher`] without an event filter. + /// + /// [pub] pub fn new( on_event: impl FnMut(Event) + std::marker::Send + 'static, capture_mode: CaptureMode, @@ -143,6 +213,9 @@ where ) } + /// Create a new [`EvidentPublisher`] with an event filter. + /// + /// [pub], [cap.filter] pub fn with( on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: F, @@ -161,10 +234,16 @@ where ) } + /// Returns the event filter, or `None` if no filter is set. + /// + /// [cap.filter] pub fn get_filter(&self) -> &Option { &self.filter } + /// Returns `true` if the given event-entry passes the filter, or the event-ID is a control-ID. + /// + /// [cap.filter] pub fn entry_allowed(&self, entry: &impl EventEntry) -> bool { if !is_control_id(entry.get_event_id()) { if !self.capturing.load(Ordering::Acquire) { @@ -181,9 +260,15 @@ where true } + /// Captures an intermediary event, and sends the resulting event to the event handler. + /// + /// **Note:** This function should **not** be called manually, because it is automatically called on `drop()` of an intermediary event. + /// + /// [cap] pub fn _capture>(&self, interm_event: &mut I) { let entry = interm_event.take_entry(); + // [cap.filter] if !self.entry_allowed(&entry) { return; } @@ -212,6 +297,7 @@ where } } + /// Returns the current capture mode. pub fn get_capture_mode(&self) -> CaptureMode { if self.capture_blocking.load(Ordering::Acquire) { CaptureMode::Blocking @@ -220,6 +306,7 @@ where } } + /// Allows to change the capture mode. pub fn set_capture_mode(&self, mode: CaptureMode) { match mode { CaptureMode::Blocking => self.capture_blocking.store(true, Ordering::Release), @@ -227,24 +314,34 @@ where } } + /// Returns the number of missed captures in *non-blocking* mode since last reset. pub fn get_missed_captures(&self) -> usize { self.missed_captures.load(Ordering::Relaxed) } + /// Resets the number of missed captures in *non-blocking* mode. pub fn reset_missed_captures(&self) { self.missed_captures.store(0, Ordering::Relaxed); } + /// Returns a subscription to events with the given event-ID, + /// or a [`SubscriptionError`] if the subscription could not be created. + /// + /// [subs.specific.one] pub fn subscribe(&self, id: K) -> Result, SubscriptionError> { self.subscribe_to_many(vec![id]) } + /// Returns a subscription to events with the given event-IDs, + /// or a [`SubscriptionError`] if the subscription could not be created. + /// + /// [subs.specific.mult] pub fn subscribe_to_many( &self, ids: Vec, ) -> Result, SubscriptionError> { // Note: Number of ids to listen to most likely affects the number of received events => number is added to channel bound - // Addition instead of multiplikation, because even distribution accross events is highly unlikely. + // Addition instead of multiplication, because even distribution accross events is highly unlikely. let (sender, receiver) = mpsc::sync_channel(ids.len() + self.subscription_channel_bound); let channel_id = crate::uuid::Uuid::new_v4(); let subscription_sender = SubscriptionSender { channel_id, sender }; @@ -278,6 +375,10 @@ where }) } + /// Returns a subscription to all events, + /// or a [`SubscriptionError`] if the subscription could not be created. + /// + /// [subs.all] pub fn subscribe_to_all_events( &self, ) -> Result, SubscriptionError> { @@ -302,10 +403,18 @@ where }) } + /// Returns `true` if capturing is *active*. + /// + /// [cap.ctrl.info] pub fn is_capturing(&self) -> bool { self.capturing.load(Ordering::Acquire) } + /// Start capturing. + /// + /// **Note:** Capturing is already started initially, so this function is only needed after manually stopping capturing. + /// + /// [cap.ctrl.start] pub fn start(&self) { let empty_msg: Option = None; let start_event = Event::new(EventEntry::new(K::start_id(), empty_msg, this_origin!())); @@ -315,6 +424,9 @@ where self.capturing.store(true, Ordering::Release); } + /// Stop capturing. + /// + /// [cap.ctrl.stop] pub fn stop(&self) { let empty_msg: Option = None; let stop_event = Event::new(EventEntry::new(K::stop_id(), empty_msg, this_origin!())); @@ -324,6 +436,11 @@ where self.capturing.store(false, Ordering::Release); } + /// Send the given event to all subscriber of the event. + /// + /// **Note:** This function should **not** be called manually, because it is already called in the event handler. + /// + /// [cap] pub fn on_event(&self, event: Event) { let arc_event = Arc::new(event); let key = arc_event.entry.get_event_id(); From cdf87a401b37dec27284a04b71895ac8f31c6e57 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 08:34:20 +0200 Subject: [PATCH 02/37] feat: add doc and req-links for creation macros --- src/creation_macros.rs | 57 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/src/creation_macros.rs b/src/creation_macros.rs index ed0e920..beef254 100644 --- a/src/creation_macros.rs +++ b/src/creation_macros.rs @@ -1,3 +1,5 @@ +//! Contains macros used to create a static publisher, and the `set_event!()` macro. + /// Macro to create a static publisher. /// /// ## Usage @@ -55,6 +57,7 @@ /// ); /// ``` /// +/// [qa.ux.macros] #[macro_export] macro_rules! create_static_publisher { ($publisher_name:ident, @@ -112,6 +115,9 @@ macro_rules! create_static_publisher { }; } +/// Internal macro to set up a static publisher. +/// +/// **Note:** Use [`create_static_publisher`](crate::create_static_publisher) instead. #[macro_export] macro_rules! z__setup_static_publisher { ($publisher_name:ident, @@ -180,6 +186,9 @@ macro_rules! z__setup_static_publisher { }; } +/// Internal macro to create a static publisher. +/// +/// **Note:** Use [`create_static_publisher`](crate::create_static_publisher) instead. #[macro_export] macro_rules! z__create_static_publisher { ($publisher_name:ident, @@ -273,6 +282,8 @@ macro_rules! z__create_static_publisher { /// interm_event_type = my_crate::my_mod::MyInterimEvent /// ); /// ``` +/// +/// [qa.ux.macros] #[macro_export] macro_rules! create_set_event_macro { (id_type = $id_t:ty, @@ -280,6 +291,29 @@ macro_rules! create_set_event_macro { entry_type = $entry_t:ty, interm_event_type = $interm_event_t:ty ) => { + /// Macro to set an event. + /// + /// **Variants:** + /// + /// - `set_event!(id)` ... Set an event for the given event-ID without a message + /// - `set_event!(id, msg)` ... Set an event for the given event-ID with the given message + /// + /// **Examples:** + /// + /// ```ignore + /// let id = YourIdType { ... }; + /// + /// set_event!(id).finalize(); + /// ``` + /// + /// ```ignore + /// let id = YourIdType { ... }; + /// let msg = "Your event message."; + /// + /// set_event!(id, msg).finalize(); + /// ``` + /// + /// [event.set], [qa.ux.macros] #[macro_export] macro_rules! set_event { ($id:expr) => { @@ -303,6 +337,29 @@ macro_rules! create_set_event_macro { entry_type = $entry_t:ty, interm_event_type = $interm_event_t:ty ) => { + /// Macro to set an event. + /// + /// **Variants:** + /// + /// - `set_event!(id)` ... Set an event for the given event-ID without a message + /// - `set_event!(id, msg)` ... Set an event for the given event-ID with the given message + /// + /// **Examples:** + /// + /// ```ignore + /// let id = YourIdType { ... }; + /// + /// set_event!(id).finalize(); + /// ``` + /// + /// ```ignore + /// let id = YourIdType { ... }; + /// let msg = "Your event message."; + /// + /// set_event!(id, msg).finalize(); + /// ``` + /// + /// [event.set], [qa.ux.macros] macro_rules! set_event { ($id:expr) => { $crate::event::set_event::<$id_t, $msg_t, $entry_t, $interm_event_t>( From fc21a47fe39bc182ae5d2631a6deff0776c20e47 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 10:29:20 +0200 Subject: [PATCH 03/37] feat: add doc and req-links to the event module --- src/event/mod.rs | 61 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 55 insertions(+), 6 deletions(-) diff --git a/src/event/mod.rs b/src/event/mod.rs index 97b6a72..22ca778 100644 --- a/src/event/mod.rs +++ b/src/event/mod.rs @@ -1,3 +1,7 @@ +//! Contains the *evident* [`Event`], and all related traits, structures, and functions. +//! +//! [event] + use std::marker::PhantomData; use self::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; @@ -8,22 +12,37 @@ pub mod finalized; pub mod intermediary; pub mod origin; +/// Trait that must be implemented for a custom *evident* ID.\ +/// This implementation must then be used for implementations of the traits [`EventEntry`], [`IntermediaryEvent`], and [`Filter`](self::filter::Filter) +/// that are used to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. +/// +/// [event.id], [event.id.generic] pub trait Id: core::fmt::Debug + Default + Clone + std::hash::Hash + PartialEq + Eq + Send + Sync + 'static { } +/// Trait that must be implemented for a custom event message.\ +/// This implementation must then be used for implementations of the traits [`EventEntry`], [`IntermediaryEvent`], and [`Filter`](self::filter::Filter) +/// that are used to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. +/// +/// **Note:** This trait is already implemented for [`String`]. +/// +/// [event.msg] pub trait Msg: core::fmt::Debug + Clone + Send + Sync + 'static {} impl Msg for String {} /// Set an event for an [`Id`] with an explicit message. +/// You may want to use [`create_set_event_macro`](crate::create_set_event_macro) to create a convenient wrapper for the `set_event` functions. /// /// # Arguments /// /// * `event_id` ... The [`Id`] used for this event /// * `msg` ... Main message that is set for this event -/// * `origin` ... The origin where the event was set (Note: Use `this_origin!()`) +/// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) +/// +/// [event.set], [event.origin] pub fn set_event_with_msg, I: IntermediaryEvent>( event_id: K, msg: impl Into, @@ -33,11 +52,14 @@ pub fn set_event_with_msg, I: IntermediaryEve } /// Set an event for an [`Id`] without a message. +/// You may want to use [`create_set_event_macro`](crate::create_set_event_macro) to create a convenient wrapper for the `set_event` functions. /// /// # Arguments /// /// * `event_id` ... The [`Id`] used for this event -/// * `origin` ... The origin where the event was set (Note: Use `this_origin!()`) +/// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) +/// +/// [event.set], [event.origin] pub fn set_event, I: IntermediaryEvent>( event_id: K, origin: Origin, @@ -46,6 +68,9 @@ pub fn set_event, I: IntermediaryEventevent] #[derive(Clone, PartialEq, Eq)] pub struct Event where @@ -53,17 +78,27 @@ where M: Msg, T: EventEntry, { + /// [`EventEntry`] of the event. + /// + /// [event.entry] pub(crate) entry: T, + + // PahmtomData needed for unused generics phantom_k: PhantomData, phantom_m: PhantomData, + /// The [`ThreadId`](std::thread::ThreadId) of the thread the event was set in. thread_id: std::thread::ThreadId, + /// The name of the thread the event was set in if a name exists. + /// Otherwise: `None` thread_name: Option, + /// The [`SystemTime`](std::time::SystemTime) when the event was set. pub(crate) timestamp: Option, } impl> Event { + /// Creates a new [`Event`] from an [`EventEntry`]. pub fn new(entry: T) -> Self { let curr_thread = std::thread::current(); @@ -79,38 +114,52 @@ impl> Event { } } - /// Returns the [`Id`] of this event + /// Returns the [`Id`] of this event. + /// + /// [event.id] pub fn get_event_id(&self) -> &K { self.entry.get_event_id() } - /// Returns the [`EventEntry`] of this event + /// Returns the [`EventEntry`] of this event. + /// + /// [event.entry] pub fn get_entry(&self) -> &T { &self.entry } + /// Get the entry-ID that was generated when the event was set. + /// + /// [event.entry.id] pub fn get_entry_id(&self) -> crate::uuid::Uuid { self.entry.get_entry_id() } - /// Get the main message that was set when the event entry was created. + /// Get the main message that was given when the event was set. + /// + /// [event.msg] pub fn get_msg(&self) -> Option<&M> { self.entry.get_msg() } + /// Get the [`Origin`] the event was set at. + /// + /// [event.origin] pub fn get_origin(&self) -> &Origin { self.entry.get_origin() } + /// Get the [`ThreadId`](std::thread::ThreadId) of the thread the event was set in. pub fn get_thread_id(&self) -> &std::thread::ThreadId { &self.thread_id } + /// Get the name of the thread the event was set in. pub fn get_thread_name(&self) -> Option<&str> { self.thread_name.as_deref() } - /// Get the timestamp of the event as UTC datetime. + /// Get the [`SystemTime`](std::time::SystemTime) timestamp of the event. pub fn get_timestamp(&self) -> &Option { &self.timestamp } From 86b4c42bc57ebdf2b2fc0a687a7e1c022b2c457e Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 11:18:18 +0200 Subject: [PATCH 04/37] feat: add doc and req-links for the EventEntry --- src/event/entry.rs | 41 ++++++++++++++++++++++++++++++++++++++++- src/event/mod.rs | 15 ++++++++++----- 2 files changed, 50 insertions(+), 6 deletions(-) diff --git a/src/event/entry.rs b/src/event/entry.rs index 4f66f91..9ddf333 100644 --- a/src/event/entry.rs +++ b/src/event/entry.rs @@ -1,18 +1,57 @@ +//! Contains the [`EventEntry] trait. +//! +//! [event.entry] + use std::hash::Hash; use super::{origin::Origin, Id, Msg}; +/// Trait that must be implemented for a custom *evident* event-entry.\ +/// This implementation must then be used for implementations of the traits [`EventEntry`] and [`IntermediaryEvent`].\ +/// All implementations are needed to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. +/// +/// The optional [`Filter`](self::filter::Filter) trait must also use the same implementation of this [`Id`] trait. +/// +/// **Note:** Since it is a trait, the custom implementation may contain additional fields and functions. +/// +/// [event.entry], [event.entry.generic] pub trait EventEntry: Default + Clone + Hash + Send + Sync + 'static { + /// Creates a new [`EventEntry`]. + /// + /// **Note:** This function should be called inside the implementation for [`IntermediaryEvent::new`](super::intermediary::IntermediaryEvent::new). + /// + /// # Arguments + /// + /// * `event_id` ... The ID of the event that was set to create this entry + /// * `msg` ... Optional main event message + /// * `origin` ... The [`Origin`] the event was set at + /// + /// [event.entry], [event.id], [event.msg], [event.origin] fn new(event_id: K, msg: Option>, origin: Origin) -> Self; + /// Returns the [`Id`] of this event. + /// + /// [event.id] fn get_event_id(&self) -> &K; + /// Convert this [`EventEntry`] into the [`Id`] of this event. + /// + /// [event.id] fn into_event_id(self) -> K; + /// Get the entry-ID that was generated when the event was set. + /// + /// [event.entry.id] fn get_entry_id(&self) -> crate::uuid::Uuid; - /// Get the main message that was set when the event entry was created. + /// Get the main message that was given when the event was set, + /// or `None` if no message was given. + /// + /// [event.msg] fn get_msg(&self) -> Option<&M>; + /// Get the [`Origin`] the event was set at. + /// + /// [event.origin] fn get_origin(&self) -> &Origin; } diff --git a/src/event/mod.rs b/src/event/mod.rs index 22ca778..88d3976 100644 --- a/src/event/mod.rs +++ b/src/event/mod.rs @@ -13,8 +13,10 @@ pub mod intermediary; pub mod origin; /// Trait that must be implemented for a custom *evident* ID.\ -/// This implementation must then be used for implementations of the traits [`EventEntry`], [`IntermediaryEvent`], and [`Filter`](self::filter::Filter) -/// that are used to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. +/// This implementation must then be used for implementations of the traits [`EventEntry`] and [`IntermediaryEvent`].\ +/// All implementations are needed to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. +/// +/// The optional [`Filter`](self::filter::Filter) trait must also use the same implementation of this [`Id`] trait. /// /// [event.id], [event.id.generic] pub trait Id: @@ -23,8 +25,10 @@ pub trait Id: } /// Trait that must be implemented for a custom event message.\ -/// This implementation must then be used for implementations of the traits [`EventEntry`], [`IntermediaryEvent`], and [`Filter`](self::filter::Filter) -/// that are used to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. +/// This implementation must then be used for implementations of the traits [`EventEntry`] and [`IntermediaryEvent`].\ +/// All implementations are needed to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. +/// +/// The optional [`Filter`](self::filter::Filter) trait must also use the same implementation of this [`Msg`] trait. /// /// **Note:** This trait is already implemented for [`String`]. /// @@ -135,7 +139,8 @@ impl> Event { self.entry.get_entry_id() } - /// Get the main message that was given when the event was set. + /// Get the main message that was given when the event was set, + /// or `None` if no message was given. /// /// [event.msg] pub fn get_msg(&self) -> Option<&M> { From 8c279577c7d8c0cc029ea5d715587b92087d54bd Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 11:32:56 +0200 Subject: [PATCH 05/37] feat: add doc and req-links for Origin --- src/event/origin.rs | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/src/event/origin.rs b/src/event/origin.rs index 305ccdb..e7ef368 100644 --- a/src/event/origin.rs +++ b/src/event/origin.rs @@ -1,17 +1,22 @@ -/// Structure representing the origin of an event. +//! Contains the [`Origin`] structure used to know where the event was set. + +/// Structure to point to a location in the program code. +/// It is used to know where the event was set, but may be used for other use cases aswell. +/// +/// [event.origin] #[derive(Debug, Default, PartialEq, Eq, Clone)] pub struct Origin { - /// Module path where the event was set. + /// Module path to the code location. /// /// Note: Use `module_path!()`. pub module_path: &'static str, - /// Filename where the event was set. + /// Filename where the code is located. /// /// Note: Use `file!()`. pub filename: &'static str, - /// Line number where the event was set. + /// Line number where the code is located. /// /// Note: Use `line!()`. pub line_nr: u32, @@ -19,6 +24,14 @@ pub struct Origin { impl Origin { /// Create a new [`Origin`]. + /// + /// # Arguments + /// + /// * `module_path` ... Module path to the code location + /// * `filename` ... Filename where the code is located + /// * `line_nr` ... Line number where the code is located + /// + /// [event.origin] pub fn new(module_path: &'static str, filename: &'static str, line_nr: u32) -> Self { Origin { module_path, @@ -29,7 +42,7 @@ impl Origin { } impl From<&Origin> for String { - /// Outputs given [`Origin`] as `crate="", module="", file="", line=`. + /// Formats given [`Origin`] as `module="", file="", line=`. fn from(origin: &Origin) -> Self { format!( "module=\"{}\", file=\"{}\", line={}", @@ -44,6 +57,9 @@ impl core::fmt::Display for Origin { } } +/// Convenience wrapper to create an [`Origin`] for the code position this macro is used at. +/// +/// [event.origin], [qa.ux.macros] #[macro_export] macro_rules! this_origin { () => { From 97e07fce0f9d47fabe016cbd8295a506b5e848f7 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 11:36:34 +0200 Subject: [PATCH 06/37] fix: update publisher macro to allow expressions --- src/creation_macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/creation_macros.rs b/src/creation_macros.rs index beef254..0f0879c 100644 --- a/src/creation_macros.rs +++ b/src/creation_macros.rs @@ -16,8 +16,8 @@ /// interm_event_type = , /// filter_type = , /// filter = , -/// capture_channel_bound = <`usize` literal for the channel bound used to capture events>, -/// subscription_channel_bound = <`usize` literal for the channel bound used per subscription>, +/// capture_channel_bound = <`usize` expression for the channel bound used to capture events>, +/// subscription_channel_bound = <`usize` expression for the channel bound used per subscription>, /// capture_mode = <`evident::publisher::CaptureMode` defining if event finalizing should be non-blocking (`NonBlocking`), or block the thread (`Blocking`)>, /// timestamp_kind = <`evident::publisher::EventTimestampKind` defining if event timestamp should be set on creation (`Created`), or on capture (`Captured`)> /// ); From 02a51340e39c8d10bf1ff1643da00f9677566462 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 12:01:11 +0200 Subject: [PATCH 07/37] fix: remove unnecessary clone when unsubscribing --- src/subscription.rs | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/src/subscription.rs b/src/subscription.rs index e3e8a62..45f4b6c 100644 --- a/src/subscription.rs +++ b/src/subscription.rs @@ -12,6 +12,9 @@ use crate::{ publisher::{CaptureControl, EvidentPublisher}, }; +/// Subscription that is returned when subscribing to events captured by an [`EvidentPublisher`]. +/// +///[subs] pub struct Subscription<'p, K, M, T, F> where K: Id + CaptureControl, @@ -19,10 +22,21 @@ where T: EventEntry, F: Filter, { + /// The ID of the channel used to send events from the publisher to the subscription. pub(crate) channel_id: crate::uuid::Uuid, + + /// The channel [`Receiver`] used to receive captured events from the publisher. pub(crate) receiver: Receiver>>, + + /// Flag set to `true` if this subscription is subscribed to receive all captured events. pub(crate) sub_to_all: bool, + + /// Optional set of event-IDs this subscription is subscribed to. + /// + /// **Note:** Only relevant for subscriptions to specific event-IDs. pub(crate) subscriptions: Option>, + + /// A reference to the publisher the subscription was created from. pub(crate) publisher: &'p EvidentPublisher, } @@ -33,18 +47,30 @@ where T: EventEntry, F: Filter, { + /// Get the [`Receiver`] of the subscription channel. pub fn get_receiver(&self) -> &Receiver>> { &self.receiver } + /// Unsubscribes this subscription. pub fn unsubscribe(self) { drop(self) } + /// Unsubscribes from the given event-ID. + /// Returns [`SubscriptionError::IdNotSubscribed`] if the ID was not subscribed, + /// or [`SubscriptionError::UnsubscribeWouldDeleteSubscription`] if the subscription would not be subscribed to any ID afterwards. + /// + /// **Note:** Only possible for subscriptions to specific IDs. pub fn unsubscribe_id(&mut self, id: K) -> Result<(), SubscriptionError> { self.unsubscribe_many(vec![id]) } + /// Unsubscribes from the given list of event-IDs. + /// Returns [`SubscriptionError::IdNotSubscribed`] if any of the IDs was not subscribed, + /// or [`SubscriptionError::UnsubscribeWouldDeleteSubscription`] if the subscription would not be subscribed to any ID afterwards. + /// + /// **Note:** Only possible for subscriptions to specific IDs. pub fn unsubscribe_many(&mut self, ids: Vec) -> Result<(), SubscriptionError> { if self.sub_to_all || self.subscriptions.is_none() { return Err(SubscriptionError::AllEventsSubscriptionNotModifiable); @@ -56,9 +82,9 @@ where return Err(SubscriptionError::UnsubscribeWouldDeleteSubscription); } - for id in ids.clone() { - if !subs.contains(&id) { - return Err(SubscriptionError::IdNotSubscribed(id)); + for id in &ids { + if !subs.contains(id) { + return Err(SubscriptionError::IdNotSubscribed(id.clone())); } } @@ -88,9 +114,9 @@ where let subs = self.subscriptions.as_mut().unwrap(); - for id in ids.clone() { - if subs.contains(&id) { - return Err(SubscriptionError::IdAlreadySubscribed(id)); + for id in &ids { + if subs.contains(id) { + return Err(SubscriptionError::IdAlreadySubscribed(id.clone())); } } let any_sub_id = match subs.iter().next() { From deec126f995ec289a1273fc70f08bc11cf40a158 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 13:44:29 +0200 Subject: [PATCH 08/37] feat: add doc and req-links to subscription module --- src/subscription.rs | 92 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 83 insertions(+), 9 deletions(-) diff --git a/src/subscription.rs b/src/subscription.rs index 45f4b6c..79b22ec 100644 --- a/src/subscription.rs +++ b/src/subscription.rs @@ -22,21 +22,21 @@ where T: EventEntry, F: Filter, { - /// The ID of the channel used to send events from the publisher to the subscription. + /// The ID of the channel used to send events from the [`EvidentPublisher`] to the [`Subscription`]. pub(crate) channel_id: crate::uuid::Uuid, - /// The channel [`Receiver`] used to receive captured events from the publisher. + /// The channel [`Receiver`] used to receive captured events from the [`EvidentPublisher`]. pub(crate) receiver: Receiver>>, - /// Flag set to `true` if this subscription is subscribed to receive all captured events. + /// Flag set to `true` if this [`Subscription`] is subscribed to receive all captured events. pub(crate) sub_to_all: bool, - /// Optional set of event-IDs this subscription is subscribed to. + /// Optional set of event-IDs this [`Subscription`] is subscribed to. /// /// **Note:** Only relevant for subscriptions to specific event-IDs. pub(crate) subscriptions: Option>, - /// A reference to the publisher the subscription was created from. + /// A reference to the [`EvidentPublisher`] the [`Subscription`] was created from. pub(crate) publisher: &'p EvidentPublisher, } @@ -58,19 +58,35 @@ where } /// Unsubscribes from the given event-ID. - /// Returns [`SubscriptionError::IdNotSubscribed`] if the ID was not subscribed, - /// or [`SubscriptionError::UnsubscribeWouldDeleteSubscription`] if the subscription would not be subscribed to any ID afterwards. /// /// **Note:** Only possible for subscriptions to specific IDs. + /// + /// # Arguments + /// + /// * `id` ... Event-ID the subscription should be unsubscribed from + /// + /// # Possible Errors + /// + /// * [`SubscriptionError::IdNotSubscribed`] ... If athe given ID was not subscribed, + /// * [`SubscriptionError::UnsubscribeWouldDeleteSubscription`] ... If the [`Subscription`] would not be subscribed to any ID afterwards + /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events pub fn unsubscribe_id(&mut self, id: K) -> Result<(), SubscriptionError> { self.unsubscribe_many(vec![id]) } /// Unsubscribes from the given list of event-IDs. - /// Returns [`SubscriptionError::IdNotSubscribed`] if any of the IDs was not subscribed, - /// or [`SubscriptionError::UnsubscribeWouldDeleteSubscription`] if the subscription would not be subscribed to any ID afterwards. /// /// **Note:** Only possible for subscriptions to specific IDs. + /// + /// # Arguments + /// + /// * `ids` ... List of event-IDs the subscription should be unsubscribed from + /// + /// # Possible Errors + /// + /// * [`SubscriptionError::IdNotSubscribed`] ... If any of the given IDs was not subscribed, + /// * [`SubscriptionError::UnsubscribeWouldDeleteSubscription`] ... If the [`Subscription`] would not be subscribed to any ID afterwards + /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events pub fn unsubscribe_many(&mut self, ids: Vec) -> Result<(), SubscriptionError> { if self.sub_to_all || self.subscriptions.is_none() { return Err(SubscriptionError::AllEventsSubscriptionNotModifiable); @@ -103,10 +119,42 @@ where } } + /// Subscribes to the given event-ID. + /// + /// **Note:** Only possible for subscriptions to specific IDs. + /// + /// # Arguments + /// + /// * `id` ... Event-ID that should be added to the subscribed IDs by the [`Subscription`] + /// + /// # Possible Errors + /// + /// * [`SubscriptionError::IdAlreadySubscribed`] ... If the given ID is already subscribed, + /// * [`SubscriptionError::CouldNotAccessPublisher`] ... If the [`Subscription`] has no connection to the [`EvidentPublisher`] + /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] + /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events + /// + /// [subs.specific.one] pub fn subscribe_id(&mut self, id: K) -> Result<(), SubscriptionError> { self.subscribe_many(vec![id]) } + /// Subscribes to the given list of event-IDs. + /// + /// **Note:** Only possible for subscriptions to specific IDs. + /// + /// # Arguments + /// + /// * `ids` ... List of event-IDs that should be added to the subscribed IDs by the [`Subscription`] + /// + /// # Possible Errors + /// + /// * [`SubscriptionError::IdAlreadySubscribed`] ... If one of the given IDs is already subscribed, + /// * [`SubscriptionError::CouldNotAccessPublisher`] ... If the [`Subscription`] has no connection to the [`EvidentPublisher`] + /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] + /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events + /// + /// [subs.specific.mult] pub fn subscribe_many(&mut self, ids: Vec) -> Result<(), SubscriptionError> { if self.sub_to_all || self.subscriptions.is_none() { return Err(SubscriptionError::AllEventsSubscriptionNotModifiable); @@ -119,6 +167,7 @@ where return Err(SubscriptionError::IdAlreadySubscribed(id.clone())); } } + // Needed to clone the *sender* of the subscription channel, which is stored in the publisher. let any_sub_id = match subs.iter().next() { Some(id) => id, None => { @@ -225,16 +274,38 @@ where } } +/// Possible errors for (un)subscribe functions. #[derive(Debug, Clone)] pub enum SubscriptionError { + /// This [`Subscription`] was created to listen to all events, which cannot be modified afterwards. AllEventsSubscriptionNotModifiable, + + /// Event-ID is not subscribed. + /// Therefore, the ID cannot be unsubscribed. + /// + /// The problematic ID may be accessed at tuple position 0. IdNotSubscribed(K), + + /// Event-ID is already subscribed. + /// Therefore, the ID cannot be re-subscribed. + /// + /// The problematic ID may be accessed at tuple position 0. IdAlreadySubscribed(K), + + /// Unsubscribing would remove all subscriptions to specific event-IDs. + /// This would remove all conntections between the [`Subscription`] and the [`EvidentPublisher`], making it impossible to modify the subscription at a later point. UnsubscribeWouldDeleteSubscription, + + /// Could not lock access to the [`EvidentPublisher`]. CouldNotAccessPublisher, + + /// No *sender-part* of the subscription-channel between this [`Subscription`] and the [`EvidentPublisher`] is available in the [`EvidentPublisher`]. NoSubscriptionChannelAvailable, } +/// *Sender-part* of the subscription-channel between a [`Subscription`] and an [`EvidentPublisher`]. +/// +/// [subs] #[derive(Clone)] pub(crate) struct SubscriptionSender where @@ -242,7 +313,10 @@ where M: Msg, T: EventEntry, { + /// ID to identify the *sender-part* in the [`EvidentPublisher`]. pub(crate) channel_id: crate::uuid::Uuid, + + /// [`SyncSender`] of the [`sync_channel`](std::sync::mpsc::sync_channel) between [`Subscription`] and [`EvidentPublisher`]. pub(crate) sender: SyncSender>>, } From cfdf2814ed37a4439e5b777f0db99a2c3b269ccf Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 14:07:41 +0200 Subject: [PATCH 09/37] feat: add doc and req-links to min-concretise test --- tests/min_concretise/entry.rs | 5 +++++ tests/min_concretise/id.rs | 12 ++++++++++++ tests/min_concretise/interim_event.rs | 5 +++++ tests/min_concretise/mod.rs | 8 +++++++- 4 files changed, 29 insertions(+), 1 deletion(-) diff --git a/tests/min_concretise/entry.rs b/tests/min_concretise/entry.rs index eafd63a..f43c875 100644 --- a/tests/min_concretise/entry.rs +++ b/tests/min_concretise/entry.rs @@ -1,7 +1,12 @@ +//! This module contains the minimal required implementation for the [`EventEntry`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, origin::Origin}; use super::id::MinId; +/// Struct used for a minimal [`EventEntry`] trait implementation. #[derive(Default, Clone)] pub struct MinEventEntry { event_id: MinId, diff --git a/tests/min_concretise/id.rs b/tests/min_concretise/id.rs index b6fca95..9f58f67 100644 --- a/tests/min_concretise/id.rs +++ b/tests/min_concretise/id.rs @@ -1,3 +1,8 @@ +//! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. +//! +//! [qa.ux.usage] + +/// Struct used for a minimal [`Id`](evident::event::Id) trait implementation. #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { pub id: isize, @@ -5,7 +10,14 @@ pub struct MinId { impl evident::event::Id for MinId {} +/// Event-ID to notify the publisher and all listeners that capturing should be started. +/// +/// [event.id.ctrl], [cap.ctrl.start] const START_CAPTURING: MinId = MinId { id: -1 }; + +/// Event-ID to notify the publisher and all listeners that capturing should be stopped. +/// +/// [event.id.ctrl], [cap.ctrl.stop] const STOP_CAPTURING: MinId = MinId { id: -2 }; impl evident::publisher::CaptureControl for MinId { diff --git a/tests/min_concretise/interim_event.rs b/tests/min_concretise/interim_event.rs index f84d46b..418109c 100644 --- a/tests/min_concretise/interim_event.rs +++ b/tests/min_concretise/interim_event.rs @@ -1,7 +1,12 @@ +//! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; use super::{entry::MinEventEntry, id::MinId}; +/// Struct used for a minimal [`IntermediaryEvent`] trait implementation. pub struct MinInterimEvent { entry: MinEventEntry, } diff --git a/tests/min_concretise/mod.rs b/tests/min_concretise/mod.rs index 31ad9c5..8b15a1d 100644 --- a/tests/min_concretise/mod.rs +++ b/tests/min_concretise/mod.rs @@ -1,3 +1,7 @@ +//! This module contains minimal required implementations to create a pub/sub-setup with *evident*. +//! +//! [qa.ux.usage] + use evident::publisher::{CaptureMode, EventTimestampKind}; use self::{entry::MinEventEntry, id::MinId, interim_event::MinInterimEvent}; @@ -6,6 +10,7 @@ mod entry; mod id; mod interim_event; +// **Note:** No *visibility modifier* set makes the `PUBLISHER` variable private to this module. evident::create_static_publisher!( PUBLISHER, id_type = MinId, @@ -18,7 +23,7 @@ evident::create_static_publisher!( timestamp_kind = EventTimestampKind::Created ); -// Note: **no_export** to prevent the macro from adding `#[macro_export]`. +// **Note:** **no_export** to prevent the macro from adding `#[macro_export]`. evident::create_set_event_macro!( no_export, id_type = MinId, @@ -27,6 +32,7 @@ evident::create_set_event_macro!( interm_event_type = MinInterimEvent ); +/// Test using the minimal pub/sub implementation to set and listen to an event. #[test] fn setup_minimal_publisher() { let some_id = MinId { id: 3 }; From 687b727f314500f71a08cdcd2b014b0d4455516c Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 14:14:53 +0200 Subject: [PATCH 10/37] feat: add doc and req-links to min-filter example --- tests/min_filter/entry.rs | 4 ++++ tests/min_filter/filter.rs | 5 +++++ tests/min_filter/id.rs | 4 ++++ tests/min_filter/interim_event.rs | 4 ++++ tests/min_filter/mod.rs | 6 ++++++ 5 files changed, 23 insertions(+) diff --git a/tests/min_filter/entry.rs b/tests/min_filter/entry.rs index eafd63a..ed276ad 100644 --- a/tests/min_filter/entry.rs +++ b/tests/min_filter/entry.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`EventEntry`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, origin::Origin}; use super::id::MinId; diff --git a/tests/min_filter/filter.rs b/tests/min_filter/filter.rs index 91d03c1..fa3af4b 100644 --- a/tests/min_filter/filter.rs +++ b/tests/min_filter/filter.rs @@ -1,7 +1,12 @@ +//! This module contains the minimal required implementation for the [`Filter`] trait. +//! +//! [qa.ux.usage] + use evident::event::filter::Filter; use super::id::MinId; +/// Struct used for a minimal [`Filter`] trait implementation. #[derive(Default)] pub struct MinFilter {} diff --git a/tests/min_filter/id.rs b/tests/min_filter/id.rs index 19b6f3c..82b59fb 100644 --- a/tests/min_filter/id.rs +++ b/tests/min_filter/id.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. +//! +//! [qa.ux.usage] + #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { pub id: isize, diff --git a/tests/min_filter/interim_event.rs b/tests/min_filter/interim_event.rs index f84d46b..2641405 100644 --- a/tests/min_filter/interim_event.rs +++ b/tests/min_filter/interim_event.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; use super::{entry::MinEventEntry, id::MinId}; diff --git a/tests/min_filter/mod.rs b/tests/min_filter/mod.rs index 4f0f8e1..c70adb7 100644 --- a/tests/min_filter/mod.rs +++ b/tests/min_filter/mod.rs @@ -1,3 +1,7 @@ +//! This module contains minimal required implementations to create a pub/sub-setup with *evident* and [`Filter`](evident::event::filter::Filter). +//! +//! [qa.ux.usage] + use evident::publisher::{CaptureMode, EventTimestampKind}; use crate::min_filter::id::STOP_CAPTURING; @@ -15,7 +19,9 @@ evident::create_static_publisher!( msg_type = String, entry_type = MinEventEntry, interm_event_type = MinInterimEvent, + // Adds the minimal filter to the publisher filter_type = MinFilter, + // Adds the minimal filter to the publisher filter = MinFilter::default(), capture_channel_bound = 1, subscription_channel_bound = 1, From 182bb3242da4d2dd0d2e872885680fa911cdac8a Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 14:19:23 +0200 Subject: [PATCH 11/37] feat: add doc and req-links to min-msg example --- tests/min_msg/entry.rs | 4 ++++ tests/min_msg/id.rs | 4 ++++ tests/min_msg/interim_event.rs | 4 ++++ tests/min_msg/mod.rs | 4 ++++ tests/min_msg/msg.rs | 5 +++++ 5 files changed, 21 insertions(+) diff --git a/tests/min_msg/entry.rs b/tests/min_msg/entry.rs index 64c4475..8e9df68 100644 --- a/tests/min_msg/entry.rs +++ b/tests/min_msg/entry.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`EventEntry`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, origin::Origin}; use super::{id::MinId, msg::MinMsg}; diff --git a/tests/min_msg/id.rs b/tests/min_msg/id.rs index b6fca95..348f389 100644 --- a/tests/min_msg/id.rs +++ b/tests/min_msg/id.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. +//! +//! [qa.ux.usage] + #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { pub id: isize, diff --git a/tests/min_msg/interim_event.rs b/tests/min_msg/interim_event.rs index 636c118..a38a3fe 100644 --- a/tests/min_msg/interim_event.rs +++ b/tests/min_msg/interim_event.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; use super::{entry::MinEventEntry, id::MinId, msg::MinMsg}; diff --git a/tests/min_msg/mod.rs b/tests/min_msg/mod.rs index b0e7cb5..9e16b20 100644 --- a/tests/min_msg/mod.rs +++ b/tests/min_msg/mod.rs @@ -1,3 +1,7 @@ +//! This module contains minimal required implementations to create a pub/sub-setup with *evident* and a custom [`Msg`](evident::event::Msg). +//! +//! [qa.ux.usage] + use evident::publisher::{CaptureMode, EventTimestampKind}; use self::{entry::MinEventEntry, id::MinId, interim_event::MinInterimEvent, msg::MinMsg}; diff --git a/tests/min_msg/msg.rs b/tests/min_msg/msg.rs index 75dd7af..c8acddf 100644 --- a/tests/min_msg/msg.rs +++ b/tests/min_msg/msg.rs @@ -1,3 +1,8 @@ +//! This module contains the minimal required implementation for the [`Msg`](evident::event::Msg) trait. +//! +//! [qa.ux.usage], [event.msg] + +/// Struct used for a minimal [`Msg`](evident::event::Msg) trait implementation. #[derive(Debug, Clone, PartialEq, Eq)] pub struct MinMsg { pub nr: usize, From cb101b8aeaeb489b9d4bd8facc164e8efbf22674 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 14:20:01 +0200 Subject: [PATCH 12/37] fix: add filter req to min-filter example --- tests/min_filter/filter.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/min_filter/filter.rs b/tests/min_filter/filter.rs index fa3af4b..8f15ebf 100644 --- a/tests/min_filter/filter.rs +++ b/tests/min_filter/filter.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Filter`] trait. //! -//! [qa.ux.usage] +//! [qa.ux.usage], [cap.filter] use evident::event::filter::Filter; From 0c0077d6fff19596901760f4663b792053928028 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 14:26:07 +0200 Subject: [PATCH 13/37] feat: add doc and req-links to min-public example --- tests/public_concretise/entry.rs | 4 ++++ tests/public_concretise/id.rs | 4 ++++ tests/public_concretise/interim_event.rs | 4 ++++ tests/public_concretise/mod.rs | 4 ++++ tests/public_concretise/public_publisher.rs | 5 +++++ 5 files changed, 21 insertions(+) diff --git a/tests/public_concretise/entry.rs b/tests/public_concretise/entry.rs index eafd63a..ed276ad 100644 --- a/tests/public_concretise/entry.rs +++ b/tests/public_concretise/entry.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`EventEntry`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, origin::Origin}; use super::id::MinId; diff --git a/tests/public_concretise/id.rs b/tests/public_concretise/id.rs index b6fca95..348f389 100644 --- a/tests/public_concretise/id.rs +++ b/tests/public_concretise/id.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. +//! +//! [qa.ux.usage] + #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { pub id: isize, diff --git a/tests/public_concretise/interim_event.rs b/tests/public_concretise/interim_event.rs index f84d46b..2641405 100644 --- a/tests/public_concretise/interim_event.rs +++ b/tests/public_concretise/interim_event.rs @@ -1,3 +1,7 @@ +//! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. +//! +//! [qa.ux.usage] + use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; use super::{entry::MinEventEntry, id::MinId}; diff --git a/tests/public_concretise/mod.rs b/tests/public_concretise/mod.rs index bde1c9e..51f2612 100644 --- a/tests/public_concretise/mod.rs +++ b/tests/public_concretise/mod.rs @@ -1,3 +1,7 @@ +//! This module contains minimal required implementations to create a pub/sub-setup with *evident* and public publisher. +//! +//! [qa.ux.usage] + use crate::public_concretise::public_publisher::PUB_PUBLISHER; use self::id::MinId; diff --git a/tests/public_concretise/public_publisher.rs b/tests/public_concretise/public_publisher.rs index 374b1ac..0d8882e 100644 --- a/tests/public_concretise/public_publisher.rs +++ b/tests/public_concretise/public_publisher.rs @@ -1,3 +1,8 @@ +//! This module creates a public [`EvidentPublisher`](evident::publisher::EvidentPublisher), +//! and the `set_event!()` macros for this publisher. +//! +//! [qa.ux.usage] + use evident::publisher::{CaptureMode, EventTimestampKind}; use crate::public_concretise::{entry::MinEventEntry, id::MinId, interim_event::MinInterimEvent}; From 3e2b643215694b00496085a5b0b805fed22855d1 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 14:56:27 +0200 Subject: [PATCH 14/37] feat: add req-links for set_event tests --- tests/pub_sub/mod.rs | 2 ++ tests/pub_sub/set_events.rs | 6 ++++++ 2 files changed, 8 insertions(+) diff --git a/tests/pub_sub/mod.rs b/tests/pub_sub/mod.rs index 0406e36..edb52c9 100644 --- a/tests/pub_sub/mod.rs +++ b/tests/pub_sub/mod.rs @@ -1,3 +1,5 @@ +//! Contains specific *evident* tests. + #[macro_use] pub(self) mod setup; diff --git a/tests/pub_sub/set_events.rs b/tests/pub_sub/set_events.rs index 03d4ea8..cf53d66 100644 --- a/tests/pub_sub/set_events.rs +++ b/tests/pub_sub/set_events.rs @@ -1,3 +1,5 @@ +//! Contains tests for the `set_event!()` macro. + use std::cmp::Ordering; use evident::event::origin::Origin; @@ -6,6 +8,7 @@ use crate::pub_sub::setup::{ entry::MinEventEntry, id::MinId, interim_event::MinInterimEvent, TESTS_PUBLISHER, }; +/// [event.origin.test.basic] #[test] fn set_event_has_correct_origin() { let id = MinId { id: 1 }; @@ -49,6 +52,7 @@ fn set_event_has_correct_origin() { ); } +/// [event.origin.test.two_origins] #[test] fn set_same_event_twice_with_different_origin() { let id = MinId { id: 1 }; @@ -100,6 +104,7 @@ fn set_same_event_twice_with_different_origin() { ); } +/// [event.origin.test.same_origin] #[test] fn set_same_event_twice_with_same_origin() { let id = MinId { id: 1 }; @@ -147,6 +152,7 @@ fn set_same_event_twice_with_same_origin() { assert_ne!(event_1, event_2, "Received events are equal."); } +/// [subs.test.mult_subs] #[test] fn set_event_received_exactly_once_per_receiver() { let id = MinId { id: 1 }; From fbd67b520baa422f74858a0df1ffa7dc58ab2942 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 16:23:53 +0200 Subject: [PATCH 15/37] feat: add cap.test req-links --- tests/min_concretise/mod.rs | 2 ++ tests/pub_sub/subscription.rs | 1 + 2 files changed, 3 insertions(+) diff --git a/tests/min_concretise/mod.rs b/tests/min_concretise/mod.rs index 8b15a1d..e09b43d 100644 --- a/tests/min_concretise/mod.rs +++ b/tests/min_concretise/mod.rs @@ -33,6 +33,8 @@ evident::create_set_event_macro!( ); /// Test using the minimal pub/sub implementation to set and listen to an event. +/// +/// [cap.test.recv] #[test] fn setup_minimal_publisher() { let some_id = MinId { id: 3 }; diff --git a/tests/pub_sub/subscription.rs b/tests/pub_sub/subscription.rs index 0f90785..8ba0efa 100644 --- a/tests/pub_sub/subscription.rs +++ b/tests/pub_sub/subscription.rs @@ -131,6 +131,7 @@ fn subscribe_to_two_ids_at_once() { ); } +/// [cap.test.mult] #[test] fn receiver_for_all_events_two_events_set() { let id_1 = MinId { id: 1 }; From 7a19efbaf33261beec8548f262150fd8f3da0f45 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 16:38:47 +0200 Subject: [PATCH 16/37] feat: add req-link for multithreaded events --- tests/pub_sub/threading.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/pub_sub/threading.rs b/tests/pub_sub/threading.rs index 7f1d358..4be5876 100644 --- a/tests/pub_sub/threading.rs +++ b/tests/pub_sub/threading.rs @@ -105,6 +105,7 @@ fn set_same_event_in_two_threads() { ); } +/// [pub.threaded.test] #[test] fn set_events_in_many_threads() { // Note: This value should be 2x lower than the channel bounds set for the publisher. From a3588bbe6a89ce5626fed1be9636d33989dd1f51 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 16:54:09 +0200 Subject: [PATCH 17/37] feat: add mult-events for single subs test --- tests/pub_sub/threading.rs | 50 +++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/tests/pub_sub/threading.rs b/tests/pub_sub/threading.rs index 4be5876..971fbc9 100644 --- a/tests/pub_sub/threading.rs +++ b/tests/pub_sub/threading.rs @@ -105,7 +105,6 @@ fn set_same_event_in_two_threads() { ); } -/// [pub.threaded.test] #[test] fn set_events_in_many_threads() { // Note: This value should be 2x lower than the channel bounds set for the publisher. @@ -164,3 +163,52 @@ fn set_events_in_many_threads() { ); } } + +/// [pub.threaded.test] +#[test] +fn set_events_in_many_threads_for_one_subscriber() { + // Note: This value should be at least 2x lower than the channel bounds set for the publisher. + // 2x lower is to make sure that the channel buffer is not the reason for this test to fail. + const THREAD_CNT: isize = 10; + let base_id = MinId { id: 1 }; + let msg = "Set event message"; + + let mut subs = TESTS_PUBLISHER.subscribe(base_id).unwrap(); + // start at 2 to jump over base_id + for i in 2..=THREAD_CNT { + let loop_id = MinId { id: i }; + subs.subscribe_id(loop_id).unwrap(); + } + + set_event!(base_id, msg).finalize(); + + rayon::scope(|s| { + // start at 2 to jump over base_id + for i in 2..=THREAD_CNT { + s.spawn(move |_| { + let loop_id = MinId { id: i }; + + // Note: `finalize()` would not be needed, since events are finalized on drop, but it makes this test easier to read + set_event!(loop_id, msg).finalize(); + }); + } + }); + + // Note: IDs might be received in any order => capture all received events, and then check if all set events are received. + + let mut recv_ids = Vec::new(); + for _ in 1..=THREAD_CNT { + let event = subs + .get_receiver() + .recv_timeout(std::time::Duration::from_millis(10)) + .unwrap(); + + recv_ids.push(event.get_event_id().clone()); + } + + for i in 1..=THREAD_CNT { + let id = MinId { id: i }; + + assert!(recv_ids.contains(&id), "Received event {} has wrong Id.", i); + } +} From 1c847b38b9740dc3078bf4fb86df5c7b476c183a Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 17:18:39 +0200 Subject: [PATCH 18/37] feat: add issue templates and CodeOfConduct --- .github/ISSUE_TEMPLATE/add-test.md | 36 +++++ .github/ISSUE_TEMPLATE/bug-report-form.yml | 41 ++++++ .github/ISSUE_TEMPLATE/bug-report.md | 37 +++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature-request.md | 27 ++++ .../ISSUE_TEMPLATE/improve-documentation.md | 17 +++ .github/ISSUE_TEMPLATE/other-topic.md | 12 ++ .github/ISSUE_TEMPLATE/spelling-mistake.md | 17 +++ .github/ISSUE_TEMPLATE/warn-us.md | 17 +++ .github/pull_request_template.md | 15 ++ CODE_OF_CONDUCT.md | 128 ++++++++++++++++++ 11 files changed, 352 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/add-test.md create mode 100644 .github/ISSUE_TEMPLATE/bug-report-form.yml create mode 100644 .github/ISSUE_TEMPLATE/bug-report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature-request.md create mode 100644 .github/ISSUE_TEMPLATE/improve-documentation.md create mode 100644 .github/ISSUE_TEMPLATE/other-topic.md create mode 100644 .github/ISSUE_TEMPLATE/spelling-mistake.md create mode 100644 .github/ISSUE_TEMPLATE/warn-us.md create mode 100644 .github/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md diff --git a/.github/ISSUE_TEMPLATE/add-test.md b/.github/ISSUE_TEMPLATE/add-test.md new file mode 100644 index 0000000..b4014e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/add-test.md @@ -0,0 +1,36 @@ +--- +name: Add Test +about: Propose a new test case. +title: "[TEST] " +labels: '' +assignees: '' + +--- + +# Describe your new test case +## Is this test case related to a problem or requirement? + +Describe your problem or requirement in a clear and concise way. +e.g. I'm always frustrated when […] + +## Describe the test case +### Describe the precondition of the test case + +Add a clear and concise description of the state the program must be in before executing the test case. + +### Describe the test case steps + +Add a clear and concise description of the test case steps. + +### Describe the postcondition of the test case + +Add a clear and concise description of the state the program must be in after executing the test case. + +## Describe alternatives you've considered + +Add a clear and concise description of any alternative pre-/postconditions or test steps you've considered. + +# Additional context + +Add any other context or screenshots about your proposed test case here. +e.g. Often, […] fails, because […] diff --git a/.github/ISSUE_TEMPLATE/bug-report-form.yml b/.github/ISSUE_TEMPLATE/bug-report-form.yml new file mode 100644 index 0000000..ff6af1f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report-form.yml @@ -0,0 +1,41 @@ +name: Bug Report Form +description: Form that guides you to create a bug report. +title: "[Bug] " +# Source partially taken from: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + - type: input + id: contact + attributes: + label: Contact Details + description: How can we get in touch with you if we need more info? + placeholder: ex. email@example.com + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Also tell us, what did you expect to happen? + placeholder: Tell us what happened! + - type: input + id: version + attributes: + label: Version + description: What version of evident where you running? + placeholder: ex. v1.0.1 or post the git commit hash + - type: textarea + id: logs + attributes: + label: Relevant log output + description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. + render: shell + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/mhatzl/evident/blob/main/CODE_OF_CONDUCT.md). + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 0000000..ffcf26e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -0,0 +1,37 @@ +--- +name: Bug Report +about: Create a bug report to help us improve. +title: "[BUG] " +labels: '' +assignees: '' + +--- + +# Describe the bug you've found + +Add a clear and concise description of what the bug is. + +# To Reproduce + +Steps to reproduce the behavior: + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error '....' + +# Expected behavior + +Add a clear and concise description of what you expected to happen. + +# Screenshots + +If applicable, add screenshots to help explain your problem. + +# Version/Branch used + +If applicable, what version/branch was used? + +# Additional context + +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..06b9459 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Project Discussions + url: https://github.com/mhatzl/evident/discussions + about: Please ask and answer questions here. diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md new file mode 100644 index 0000000..e04b51b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -0,0 +1,27 @@ +--- +name: Feature Request +about: Tell us about a feature you need. +title: "[REQ] " +labels: '' +assignees: '' + +--- + +# Describe your feature request +## Is your feature request related to a problem or requirement? + +Describe your problem or requirement in a clear and concise way. +e.g. I'm always frustrated when […] + +## Describe the solution you'd like + +Add a clear and concise description of what you want to happen. + +## Describe alternatives you've considered + +Add a clear and concise description of any alternative solutions or features you've considered. + +# Additional context + +Add any other context or screenshots about your feature request here. +e.g. I often want to do […], because […] diff --git a/.github/ISSUE_TEMPLATE/improve-documentation.md b/.github/ISSUE_TEMPLATE/improve-documentation.md new file mode 100644 index 0000000..c8fe6c4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/improve-documentation.md @@ -0,0 +1,17 @@ +--- +name: Improve Documentation +about: Is there something you do not understand? +title: "[DOC] " +labels: '' +assignees: '' + +--- + +# Describe your problem with the current documentation +## Describe what is/was unclear to you + +Add a clear and concise description about why the documentation is/was unclear to you. + +## Describe what would help you do better understand the problem + +Add a clear and concise description about what would help you to better understand the problem. diff --git a/.github/ISSUE_TEMPLATE/other-topic.md b/.github/ISSUE_TEMPLATE/other-topic.md new file mode 100644 index 0000000..b4981a3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/other-topic.md @@ -0,0 +1,12 @@ +--- +name: Other Topic +about: Select if you are not sure what else to choose. +title: "[OTHER] " +labels: '' +assignees: '' + +--- + +# Describe your problem + +Add a clear and concise description about your problem. diff --git a/.github/ISSUE_TEMPLATE/spelling-mistake.md b/.github/ISSUE_TEMPLATE/spelling-mistake.md new file mode 100644 index 0000000..86eba38 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/spelling-mistake.md @@ -0,0 +1,17 @@ +--- +name: Spelling Mistake +about: Help us improve our spelling. +title: "[SPELL] " +labels: '' +assignees: '' + +--- + +# Describe the spelling mistake +## Describe the location(s) of the spelling mistake + +Link to or add a screenshot of the location of the spelling mistake. + +## Describe the mistake + +Add a clear and concise description about what the correct way would be and why? diff --git a/.github/ISSUE_TEMPLATE/warn-us.md b/.github/ISSUE_TEMPLATE/warn-us.md new file mode 100644 index 0000000..3d49ea4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/warn-us.md @@ -0,0 +1,17 @@ +--- +name: Warn Us +about: Warn us about a possible problem. +title: "[WARN] " +labels: '' +assignees: '' + +--- + +# Describe your warning +## Describe the problem you want to warn us about + +Add a clear and concise description about the problem you want to warn us about. + +## Describe what you suggest to do + +Add a clear and concise description about your suggested solution to prevent the problem. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..1971225 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +# List of issues that this PR closes + +e.g. closes #1 closes #2 … + +# Have you considered the following requirements? + +- [ ] Add usage examples in doc-comments (see: [qa.ux.usage]) +- [ ] Only use macros if they improve *evident's* usability (see: [qa.ux.macros]) +- [ ] Prefer `RwLock` over `Mutex` (see: [qa.perf.locks]) + +**Note:** You may ignore requirements that are not relevant to your PR. + +# Describe how you fixed the issue(s) + +Add a clear and concise description about how you fixed the issue(s). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..30c8060 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[@HatzlManuel](https://twitter.com/HatzlManuel). +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. From 132e872c9c6c67b0efa713767f4e567588523b2a Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 17:31:23 +0200 Subject: [PATCH 19/37] feat: add git-hooks for commit structure checks --- .hooks/commit-msg | 49 +++++++++++++++++++++++++++++++++++++++++++++++ .hooks/pre-push | 6 ++++++ 2 files changed, 55 insertions(+) create mode 100644 .hooks/commit-msg create mode 100644 .hooks/pre-push diff --git a/.hooks/commit-msg b/.hooks/commit-msg new file mode 100644 index 0000000..d08e0bf --- /dev/null +++ b/.hooks/commit-msg @@ -0,0 +1,49 @@ +#!/bin/bash + +# first (and only) argument is whether we abort commit or not +print_help() { + if $1; then + echo -e "Aborting commit! Your commit message does not follow the Conventional Commits Specification.\n" >&2 + fi + + echo -e "Commit message structure: \n" >&2 + + echo -e "\t: " >&2 + + echo -e "\n\t[]" >&2 + + echo -e "\n\t[]" >&2 + + echo -e "\nWhere ': ' is not longer than 50 characters and is one of:\n" >&2 + + echo -e "- feat \t\t... Use if commit adds a new feature" >&2 + echo -e "- fix \t\t... Use if commit fixes a bug of any kind" >&2 + echo -e "- arch \t\t... Use if commit neither adds features nor fixes bugs (e.g. renaming or restructuring)" >&2 + echo -e "- chore \t... Miscellaneous (should only be used for automatically generated commits)" >&2 + + echo -e "\nNOTE: If your commit fits to types 'feat' and 'fix', try to split your commit." >&2 + + echo -e "NOTE: may be immediately followed by a '!' to indicate breaking changes." >&2 + echo -e "NOTE: Use '!' instead of writing 'BREAKING CHANGE: ' in the '[]'.\n" >&2 + + echo -e "Examples: \n" >&2 + echo -e "feat: improve log message on bad request" >&2 + echo -e "feat!: indicate a breaking change" >&2 + echo -e "fix: fix some bug" >&2 + echo -e "\nFor more information, see: \nhttps://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines \nhttps://www.conventionalcommits.org/en/v1.0.0/" >&2 +} + +RED="\033[31m" +YELLOW="\033[33m" +CLEAR="\033[0m" + +if ! head -1 "$1" | grep -qE "^(feat|fix|arch|chore)[!]?: .{1,}$"; then + echo -e "${RED}\nERROR: Given commit type is wrong!${CLEAR}\n" >&2 + print_help true + + exit 1 +fi +if ! head -1 "$1" | grep -qE "^.{1,50}$"; then + echo -e "${YELLOW}\nWARNING: ': ' should not have more than 50 characters!${CLEAR}\n" >&2 + print_help false +fi \ No newline at end of file diff --git a/.hooks/pre-push b/.hooks/pre-push new file mode 100644 index 0000000..554740f --- /dev/null +++ b/.hooks/pre-push @@ -0,0 +1,6 @@ +#!/bin/bash + +# Use this hook to run linting and check code formatting. +# Abort if linting or formatting return any errors or warnings. + + From b726346a771a5ebcffdc4f8a9ba671376e2feff9 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 10 Aug 2023 17:36:14 +0200 Subject: [PATCH 20/37] feat: add release and auto-lock actions --- .github/workflows/auto-lock-prs.yml | 22 +++++++++++++++++++ .github/workflows/release-please.yml | 32 ++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 .github/workflows/auto-lock-prs.yml create mode 100644 .github/workflows/release-please.yml diff --git a/.github/workflows/auto-lock-prs.yml b/.github/workflows/auto-lock-prs.yml new file mode 100644 index 0000000..c0ab7ac --- /dev/null +++ b/.github/workflows/auto-lock-prs.yml @@ -0,0 +1,22 @@ +# Action to automatically lock PRs after they are merged or closed. +name: "auto-lock PRs" +on: + pull_request_target: + types: [closed] + +jobs: + lock-closed-PRs: + runs-on: ubuntu-latest + permissions: + issues: write + pull-requests: write + steps: + - uses: actions/github-script@v6 + with: + script: | + github.rest.issues.lock({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + lock_reason: "resolved" + }) diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml new file mode 100644 index 0000000..04c19ad --- /dev/null +++ b/.github/workflows/release-please.yml @@ -0,0 +1,32 @@ +on: + push: + branches: + - main + +# See: https://github.com/google-github-actions/release-please-action +name: Release Please + +permissions: + contents: write + pull-requests: write + +jobs: + release-please: + runs-on: ubuntu-latest + steps: + - uses: GoogleCloudPlatform/release-please-action@v3 + with: + # Change type and name depending on your repository + # See: https://github.com/google-github-actions/release-please-action#release-types-supported + release-type: rust + package-name: evident + pull-request-title-pattern: "chore: release${component} ${version}" + # Breaking changes might happen frequently before 1.0.0 => only bump minor + bump-minor-pre-major: true + changelog-types: > + [ + {"type":"feat","section":"Features","hidden":false}, + {"type":"fix","section":"Bug Fixes","hidden":false}, + {"type":"arch","section":"Architectur/Refactor","hidden":false}, + {"type":"chore","section":"Miscellaneous","hidden":true} + ] From 466f3a748fd8806fab949fb6f21e782e89b1c95d Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Fri, 11 Aug 2023 14:56:53 +0200 Subject: [PATCH 21/37] feat: add DoD and qa-req links --- .github/pull_request_template.md | 5 ++++- .github/workflows/rust.yml | 7 +++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 1971225..8758a75 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,8 +2,11 @@ e.g. closes #1 closes #2 … -# Have you considered the following requirements? +# General "Definition of Done" ([qa.DoD]) +**Please consider the following requirements:** + +- [ ] Add/Update requirement tags (see: [qa.links]) - [ ] Add usage examples in doc-comments (see: [qa.ux.usage]) - [ ] Only use macros if they improve *evident's* usability (see: [qa.ux.macros]) - [ ] Prefer `RwLock` over `Mutex` (see: [qa.perf.locks]) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 9d0168f..d3a05a1 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -10,6 +10,7 @@ env: CARGO_TERM_COLOR: always jobs: + # [qa.pipeline.1_style] format: name: Check Formatting runs-on: ubuntu-latest @@ -19,9 +20,11 @@ jobs: - name: Run cargo fmt run: cargo fmt -- --check + # [qa.pipeline.2_lint] lint: name: Run Linter (clippy) runs-on: ubuntu-latest + # [qa.sustain] needs: format steps: @@ -29,9 +32,11 @@ jobs: - name: Run linter run: cargo clippy -- -D warnings + # [qa.pipeline.3_build] build: name: Run Build runs-on: ubuntu-latest + # [qa.sustain] needs: lint steps: @@ -39,9 +44,11 @@ jobs: - name: Build run: cargo build --verbose + # [qa.pipeline.4_tests] test: name: Run Tests runs-on: ubuntu-latest + # [qa.sustain] needs: build steps: From 46491331c819f533ed786356833e506c839a6290 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 16 Aug 2023 09:40:27 +0200 Subject: [PATCH 22/37] fix: replace req-tag syntax --- .github/pull_request_template.md | 10 ++-- .github/workflows/rust.yml | 14 ++--- src/creation_macros.rs | 8 +-- src/event/entry.rs | 16 +++--- src/event/mod.rs | 24 ++++----- src/event/origin.rs | 6 +-- src/publisher.rs | 60 ++++++++++----------- src/subscription.rs | 8 +-- tests/min_concretise/entry.rs | 2 +- tests/min_concretise/id.rs | 6 +-- tests/min_concretise/interim_event.rs | 2 +- tests/min_concretise/mod.rs | 4 +- tests/min_filter/entry.rs | 2 +- tests/min_filter/filter.rs | 2 +- tests/min_filter/id.rs | 2 +- tests/min_filter/interim_event.rs | 2 +- tests/min_filter/mod.rs | 2 +- tests/min_msg/entry.rs | 2 +- tests/min_msg/id.rs | 2 +- tests/min_msg/interim_event.rs | 2 +- tests/min_msg/mod.rs | 2 +- tests/min_msg/msg.rs | 2 +- tests/pub_sub/set_events.rs | 8 +-- tests/pub_sub/subscription.rs | 2 +- tests/pub_sub/threading.rs | 2 +- tests/public_concretise/entry.rs | 2 +- tests/public_concretise/id.rs | 2 +- tests/public_concretise/interim_event.rs | 2 +- tests/public_concretise/mod.rs | 2 +- tests/public_concretise/public_publisher.rs | 2 +- 30 files changed, 101 insertions(+), 101 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8758a75..bed902a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,14 +2,14 @@ e.g. closes #1 closes #2 … -# General "Definition of Done" ([qa.DoD]) +# General "Definition of Done" ([req:qa.DoD]) **Please consider the following requirements:** -- [ ] Add/Update requirement tags (see: [qa.links]) -- [ ] Add usage examples in doc-comments (see: [qa.ux.usage]) -- [ ] Only use macros if they improve *evident's* usability (see: [qa.ux.macros]) -- [ ] Prefer `RwLock` over `Mutex` (see: [qa.perf.locks]) +- [ ] Add/Update requirement tags (see: [req:qa.links]) +- [ ] Add usage examples in doc-comments (see: [req:qa.ux.usage]) +- [ ] Only use macros if they improve *evident's* usability (see: [req:qa.ux.macros]) +- [ ] Prefer `RwLock` over `Mutex` (see: [req:qa.perf.locks]) **Note:** You may ignore requirements that are not relevant to your PR. diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index d3a05a1..a538c25 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -10,7 +10,7 @@ env: CARGO_TERM_COLOR: always jobs: - # [qa.pipeline.1_style] + # [req:qa.pipeline.1_style] format: name: Check Formatting runs-on: ubuntu-latest @@ -20,11 +20,11 @@ jobs: - name: Run cargo fmt run: cargo fmt -- --check - # [qa.pipeline.2_lint] + # [req:qa.pipeline.2_lint] lint: name: Run Linter (clippy) runs-on: ubuntu-latest - # [qa.sustain] + # [req:qa.sustain] needs: format steps: @@ -32,11 +32,11 @@ jobs: - name: Run linter run: cargo clippy -- -D warnings - # [qa.pipeline.3_build] + # [req:qa.pipeline.3_build] build: name: Run Build runs-on: ubuntu-latest - # [qa.sustain] + # [req:qa.sustain] needs: lint steps: @@ -44,11 +44,11 @@ jobs: - name: Build run: cargo build --verbose - # [qa.pipeline.4_tests] + # [req:qa.pipeline.4_tests] test: name: Run Tests runs-on: ubuntu-latest - # [qa.sustain] + # [req:qa.sustain] needs: build steps: diff --git a/src/creation_macros.rs b/src/creation_macros.rs index 0f0879c..11e0421 100644 --- a/src/creation_macros.rs +++ b/src/creation_macros.rs @@ -57,7 +57,7 @@ /// ); /// ``` /// -/// [qa.ux.macros] +/// [req:qa.ux.macros] #[macro_export] macro_rules! create_static_publisher { ($publisher_name:ident, @@ -283,7 +283,7 @@ macro_rules! z__create_static_publisher { /// ); /// ``` /// -/// [qa.ux.macros] +/// [req:qa.ux.macros] #[macro_export] macro_rules! create_set_event_macro { (id_type = $id_t:ty, @@ -313,7 +313,7 @@ macro_rules! create_set_event_macro { /// set_event!(id, msg).finalize(); /// ``` /// - /// [event.set], [qa.ux.macros] + /// [req:event.set], [req:qa.ux.macros] #[macro_export] macro_rules! set_event { ($id:expr) => { @@ -359,7 +359,7 @@ macro_rules! create_set_event_macro { /// set_event!(id, msg).finalize(); /// ``` /// - /// [event.set], [qa.ux.macros] + /// [req:event.set], [req:qa.ux.macros] macro_rules! set_event { ($id:expr) => { $crate::event::set_event::<$id_t, $msg_t, $entry_t, $interm_event_t>( diff --git a/src/event/entry.rs b/src/event/entry.rs index 9ddf333..6d9469a 100644 --- a/src/event/entry.rs +++ b/src/event/entry.rs @@ -1,6 +1,6 @@ //! Contains the [`EventEntry] trait. //! -//! [event.entry] +//! [req:event.entry] use std::hash::Hash; @@ -14,7 +14,7 @@ use super::{origin::Origin, Id, Msg}; /// /// **Note:** Since it is a trait, the custom implementation may contain additional fields and functions. /// -/// [event.entry], [event.entry.generic] +/// [req:event.entry], [req:event.entry.generic] pub trait EventEntry: Default + Clone + Hash + Send + Sync + 'static { /// Creates a new [`EventEntry`]. /// @@ -26,32 +26,32 @@ pub trait EventEntry: Default + Clone + Hash + Send + Sync + 'sta /// * `msg` ... Optional main event message /// * `origin` ... The [`Origin`] the event was set at /// - /// [event.entry], [event.id], [event.msg], [event.origin] + /// [req:event.entry], [req:event.id], [req:event.msg], [req:event.origin] fn new(event_id: K, msg: Option>, origin: Origin) -> Self; /// Returns the [`Id`] of this event. /// - /// [event.id] + /// [req:event.id] fn get_event_id(&self) -> &K; /// Convert this [`EventEntry`] into the [`Id`] of this event. /// - /// [event.id] + /// [req:event.id] fn into_event_id(self) -> K; /// Get the entry-ID that was generated when the event was set. /// - /// [event.entry.id] + /// [req:event.entry.id] fn get_entry_id(&self) -> crate::uuid::Uuid; /// Get the main message that was given when the event was set, /// or `None` if no message was given. /// - /// [event.msg] + /// [req:event.msg] fn get_msg(&self) -> Option<&M>; /// Get the [`Origin`] the event was set at. /// - /// [event.origin] + /// [req:event.origin] fn get_origin(&self) -> &Origin; } diff --git a/src/event/mod.rs b/src/event/mod.rs index 88d3976..865c8f7 100644 --- a/src/event/mod.rs +++ b/src/event/mod.rs @@ -1,6 +1,6 @@ //! Contains the *evident* [`Event`], and all related traits, structures, and functions. //! -//! [event] +//! [req:event] use std::marker::PhantomData; @@ -18,7 +18,7 @@ pub mod origin; /// /// The optional [`Filter`](self::filter::Filter) trait must also use the same implementation of this [`Id`] trait. /// -/// [event.id], [event.id.generic] +/// [req:event.id], [req:event.id.generic] pub trait Id: core::fmt::Debug + Default + Clone + std::hash::Hash + PartialEq + Eq + Send + Sync + 'static { @@ -32,7 +32,7 @@ pub trait Id: /// /// **Note:** This trait is already implemented for [`String`]. /// -/// [event.msg] +/// [req:event.msg] pub trait Msg: core::fmt::Debug + Clone + Send + Sync + 'static {} impl Msg for String {} @@ -46,7 +46,7 @@ impl Msg for String {} /// * `msg` ... Main message that is set for this event /// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) /// -/// [event.set], [event.origin] +/// [req:event.set], [req:event.origin] pub fn set_event_with_msg, I: IntermediaryEvent>( event_id: K, msg: impl Into, @@ -63,7 +63,7 @@ pub fn set_event_with_msg, I: IntermediaryEve /// * `event_id` ... The [`Id`] used for this event /// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) /// -/// [event.set], [event.origin] +/// [req:event.set], [req:event.origin] pub fn set_event, I: IntermediaryEvent>( event_id: K, origin: Origin, @@ -74,7 +74,7 @@ pub fn set_event, I: IntermediaryEventevent] +/// [req:event] #[derive(Clone, PartialEq, Eq)] pub struct Event where @@ -84,7 +84,7 @@ where { /// [`EventEntry`] of the event. /// - /// [event.entry] + /// [req:event.entry] pub(crate) entry: T, // PahmtomData needed for unused generics @@ -120,21 +120,21 @@ impl> Event { /// Returns the [`Id`] of this event. /// - /// [event.id] + /// [req:event.id] pub fn get_event_id(&self) -> &K { self.entry.get_event_id() } /// Returns the [`EventEntry`] of this event. /// - /// [event.entry] + /// [req:event.entry] pub fn get_entry(&self) -> &T { &self.entry } /// Get the entry-ID that was generated when the event was set. /// - /// [event.entry.id] + /// [req:event.entry.id] pub fn get_entry_id(&self) -> crate::uuid::Uuid { self.entry.get_entry_id() } @@ -142,14 +142,14 @@ impl> Event { /// Get the main message that was given when the event was set, /// or `None` if no message was given. /// - /// [event.msg] + /// [req:event.msg] pub fn get_msg(&self) -> Option<&M> { self.entry.get_msg() } /// Get the [`Origin`] the event was set at. /// - /// [event.origin] + /// [req:event.origin] pub fn get_origin(&self) -> &Origin { self.entry.get_origin() } diff --git a/src/event/origin.rs b/src/event/origin.rs index e7ef368..8e12bbf 100644 --- a/src/event/origin.rs +++ b/src/event/origin.rs @@ -3,7 +3,7 @@ /// Structure to point to a location in the program code. /// It is used to know where the event was set, but may be used for other use cases aswell. /// -/// [event.origin] +/// [req:event.origin] #[derive(Debug, Default, PartialEq, Eq, Clone)] pub struct Origin { /// Module path to the code location. @@ -31,7 +31,7 @@ impl Origin { /// * `filename` ... Filename where the code is located /// * `line_nr` ... Line number where the code is located /// - /// [event.origin] + /// [req:event.origin] pub fn new(module_path: &'static str, filename: &'static str, line_nr: u32) -> Self { Origin { module_path, @@ -59,7 +59,7 @@ impl core::fmt::Display for Origin { /// Convenience wrapper to create an [`Origin`] for the code position this macro is used at. /// -/// [event.origin], [qa.ux.macros] +/// [req:event.origin], [req:qa.ux.macros] #[macro_export] macro_rules! this_origin { () => { diff --git a/src/publisher.rs b/src/publisher.rs index 0a606d1..5e049f3 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -16,7 +16,7 @@ use crate::{ /// Trait to implement for [`Id`], to control the publisher and all listeners. /// -/// [cap.ctrl](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrl-control-capturing) +/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrl-control-capturing) pub trait CaptureControl { /// Returns `true` if the given [`Id`] is used to signal the start of event capturing. /// @@ -26,12 +26,12 @@ pub trait CaptureControl { /// id == &START_CAPTURING_ID /// ``` /// - /// [cap.ctrl.start] + /// [req:cap.ctrl.start] fn start(id: &Self) -> bool; /// Returns the *start-ID*. /// - /// [cap.ctrl.start] + /// [req:cap.ctrl.start] fn start_id() -> Self; /// Returns `true` if the given [`Id`] is used to signal the end of event capturing. @@ -42,18 +42,18 @@ pub trait CaptureControl { /// id == &STOP_CAPTURING_ID /// ``` /// - /// [cap.ctrl.stop] + /// [req:cap.ctrl.stop] fn stop(id: &Self) -> bool; /// Returns the *stop-ID*. /// - /// [cap.ctrl.stop] + /// [req:cap.ctrl.stop] fn stop_id() -> Self; } /// Returns `true` if the given [`Id`] is used to control capturing. /// -/// [cap.ctrl] +/// [req:cap.ctrl] pub fn is_control_id(id: &impl CaptureControl) -> bool { CaptureControl::stop(id) || CaptureControl::start(id) } @@ -88,7 +88,7 @@ type Capturer = SyncSender>; /// /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. /// -/// [pub] +/// [req:pub] pub struct EvidentPublisher where K: Id + CaptureControl, @@ -98,27 +98,27 @@ where { /// The hashmap of subscribers listening to specific events. /// - /// [subs.specific] + /// [req:subs.specific] pub(crate) subscriptions: Arc>>, /// The hashmap of subscribers listening to all events. /// - /// [subs.all] + /// [req:subs.all] pub(crate) any_event: Arc>>, /// The send-part of the capturing channel. /// - /// [cap] + /// [req:cap] pub(crate) capturer: Capturer, /// Optional filter that is applied when capturing events. /// - /// [cap.filter] + /// [req:cap.filter] filter: Option, /// Flag to control if capturing is active or inactive. /// - /// [cap.ctrl] + /// [req:cap.ctrl] capturing: Arc, /// Flag to control the capture mode. @@ -126,12 +126,12 @@ where /// Defines the size of the capturing send-buffer. /// - /// [cap] + /// [req:cap] capture_channel_bound: usize, /// Defines the size of each subscription send-buffer. /// - /// [subs] + /// [req:subs] subscription_channel_bound: usize, /// Number of missed captures in *non-blocking* capture mode. @@ -150,7 +150,7 @@ where { /// Create a new [`EvidentPublisher`], and spawn a new event handler thread for events captured by the publisher. /// - /// [pub] + /// [req:pub] fn create( mut on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: Option, @@ -162,7 +162,7 @@ where let (send, recv): (SyncSender>, _) = mpsc::sync_channel(capture_channel_bound); - // [pub.threaded] + // [req:pub.threaded] thread::spawn(move || { while let Ok(mut event) = recv.recv() { if timestamp_kind == EventTimestampKind::Captured { @@ -183,7 +183,7 @@ where any_event: Arc::new(RwLock::new(HashMap::new())), capturer: send, filter, - // [cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrlinit-initial-capturing-state) + // [req:cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrlinit-initial-capturing-state) capturing: Arc::new(AtomicBool::new(true)), capture_blocking: mode, capture_channel_bound, @@ -195,7 +195,7 @@ where /// Create a new [`EvidentPublisher`] without an event filter. /// - /// [pub] + /// [req:pub] pub fn new( on_event: impl FnMut(Event) + std::marker::Send + 'static, capture_mode: CaptureMode, @@ -215,7 +215,7 @@ where /// Create a new [`EvidentPublisher`] with an event filter. /// - /// [pub], [cap.filter] + /// [req:pub], [req:cap.filter] pub fn with( on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: F, @@ -236,14 +236,14 @@ where /// Returns the event filter, or `None` if no filter is set. /// - /// [cap.filter] + /// [req:cap.filter] pub fn get_filter(&self) -> &Option { &self.filter } /// Returns `true` if the given event-entry passes the filter, or the event-ID is a control-ID. /// - /// [cap.filter] + /// [req:cap.filter] pub fn entry_allowed(&self, entry: &impl EventEntry) -> bool { if !is_control_id(entry.get_event_id()) { if !self.capturing.load(Ordering::Acquire) { @@ -264,11 +264,11 @@ where /// /// **Note:** This function should **not** be called manually, because it is automatically called on `drop()` of an intermediary event. /// - /// [cap] + /// [req:cap] pub fn _capture>(&self, interm_event: &mut I) { let entry = interm_event.take_entry(); - // [cap.filter] + // [req:cap.filter] if !self.entry_allowed(&entry) { return; } @@ -327,7 +327,7 @@ where /// Returns a subscription to events with the given event-ID, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [subs.specific.one] + /// [req:subs.specific.one] pub fn subscribe(&self, id: K) -> Result, SubscriptionError> { self.subscribe_to_many(vec![id]) } @@ -335,7 +335,7 @@ where /// Returns a subscription to events with the given event-IDs, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [subs.specific.mult] + /// [req:subs.specific.mult] pub fn subscribe_to_many( &self, ids: Vec, @@ -378,7 +378,7 @@ where /// Returns a subscription to all events, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [subs.all] + /// [req:subs.all] pub fn subscribe_to_all_events( &self, ) -> Result, SubscriptionError> { @@ -405,7 +405,7 @@ where /// Returns `true` if capturing is *active*. /// - /// [cap.ctrl.info] + /// [req:cap.ctrl.info] pub fn is_capturing(&self) -> bool { self.capturing.load(Ordering::Acquire) } @@ -414,7 +414,7 @@ where /// /// **Note:** Capturing is already started initially, so this function is only needed after manually stopping capturing. /// - /// [cap.ctrl.start] + /// [req:cap.ctrl.start] pub fn start(&self) { let empty_msg: Option = None; let start_event = Event::new(EventEntry::new(K::start_id(), empty_msg, this_origin!())); @@ -426,7 +426,7 @@ where /// Stop capturing. /// - /// [cap.ctrl.stop] + /// [req:cap.ctrl.stop] pub fn stop(&self) { let empty_msg: Option = None; let stop_event = Event::new(EventEntry::new(K::stop_id(), empty_msg, this_origin!())); @@ -440,7 +440,7 @@ where /// /// **Note:** This function should **not** be called manually, because it is already called in the event handler. /// - /// [cap] + /// [req:cap] pub fn on_event(&self, event: Event) { let arc_event = Arc::new(event); let key = arc_event.entry.get_event_id(); diff --git a/src/subscription.rs b/src/subscription.rs index 79b22ec..22d1333 100644 --- a/src/subscription.rs +++ b/src/subscription.rs @@ -14,7 +14,7 @@ use crate::{ /// Subscription that is returned when subscribing to events captured by an [`EvidentPublisher`]. /// -///[subs] +///[req:subs] pub struct Subscription<'p, K, M, T, F> where K: Id + CaptureControl, @@ -134,7 +134,7 @@ where /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events /// - /// [subs.specific.one] + /// [req:subs.specific.one] pub fn subscribe_id(&mut self, id: K) -> Result<(), SubscriptionError> { self.subscribe_many(vec![id]) } @@ -154,7 +154,7 @@ where /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events /// - /// [subs.specific.mult] + /// [req:subs.specific.mult] pub fn subscribe_many(&mut self, ids: Vec) -> Result<(), SubscriptionError> { if self.sub_to_all || self.subscriptions.is_none() { return Err(SubscriptionError::AllEventsSubscriptionNotModifiable); @@ -305,7 +305,7 @@ pub enum SubscriptionError { /// *Sender-part* of the subscription-channel between a [`Subscription`] and an [`EvidentPublisher`]. /// -/// [subs] +/// [req:subs] #[derive(Clone)] pub(crate) struct SubscriptionSender where diff --git a/tests/min_concretise/entry.rs b/tests/min_concretise/entry.rs index f43c875..2c15175 100644 --- a/tests/min_concretise/entry.rs +++ b/tests/min_concretise/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_concretise/id.rs b/tests/min_concretise/id.rs index 9f58f67..09a8011 100644 --- a/tests/min_concretise/id.rs +++ b/tests/min_concretise/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] /// Struct used for a minimal [`Id`](evident::event::Id) trait implementation. #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] @@ -12,12 +12,12 @@ impl evident::event::Id for MinId {} /// Event-ID to notify the publisher and all listeners that capturing should be started. /// -/// [event.id.ctrl], [cap.ctrl.start] +/// [req:event.id.ctrl], [req:cap.ctrl.start] const START_CAPTURING: MinId = MinId { id: -1 }; /// Event-ID to notify the publisher and all listeners that capturing should be stopped. /// -/// [event.id.ctrl], [cap.ctrl.stop] +/// [req:event.id.ctrl], [req:cap.ctrl.stop] const STOP_CAPTURING: MinId = MinId { id: -2 }; impl evident::publisher::CaptureControl for MinId { diff --git a/tests/min_concretise/interim_event.rs b/tests/min_concretise/interim_event.rs index 418109c..6b5ac12 100644 --- a/tests/min_concretise/interim_event.rs +++ b/tests/min_concretise/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_concretise/mod.rs b/tests/min_concretise/mod.rs index e09b43d..b7e9dcf 100644 --- a/tests/min_concretise/mod.rs +++ b/tests/min_concretise/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident*. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; @@ -34,7 +34,7 @@ evident::create_set_event_macro!( /// Test using the minimal pub/sub implementation to set and listen to an event. /// -/// [cap.test.recv] +/// [req:cap.test.recv] #[test] fn setup_minimal_publisher() { let some_id = MinId { id: 3 }; diff --git a/tests/min_filter/entry.rs b/tests/min_filter/entry.rs index ed276ad..135ecf2 100644 --- a/tests/min_filter/entry.rs +++ b/tests/min_filter/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_filter/filter.rs b/tests/min_filter/filter.rs index 8f15ebf..32823e4 100644 --- a/tests/min_filter/filter.rs +++ b/tests/min_filter/filter.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Filter`] trait. //! -//! [qa.ux.usage], [cap.filter] +//! [req:qa.ux.usage], [req:cap.filter] use evident::event::filter::Filter; diff --git a/tests/min_filter/id.rs b/tests/min_filter/id.rs index 82b59fb..06261fe 100644 --- a/tests/min_filter/id.rs +++ b/tests/min_filter/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/min_filter/interim_event.rs b/tests/min_filter/interim_event.rs index 2641405..0186ef1 100644 --- a/tests/min_filter/interim_event.rs +++ b/tests/min_filter/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_filter/mod.rs b/tests/min_filter/mod.rs index c70adb7..34998e5 100644 --- a/tests/min_filter/mod.rs +++ b/tests/min_filter/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and [`Filter`](evident::event::filter::Filter). //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; diff --git a/tests/min_msg/entry.rs b/tests/min_msg/entry.rs index 8e9df68..430f74c 100644 --- a/tests/min_msg/entry.rs +++ b/tests/min_msg/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_msg/id.rs b/tests/min_msg/id.rs index 348f389..b2c777a 100644 --- a/tests/min_msg/id.rs +++ b/tests/min_msg/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/min_msg/interim_event.rs b/tests/min_msg/interim_event.rs index a38a3fe..8f5b33b 100644 --- a/tests/min_msg/interim_event.rs +++ b/tests/min_msg/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_msg/mod.rs b/tests/min_msg/mod.rs index 9e16b20..411d540 100644 --- a/tests/min_msg/mod.rs +++ b/tests/min_msg/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and a custom [`Msg`](evident::event::Msg). //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; diff --git a/tests/min_msg/msg.rs b/tests/min_msg/msg.rs index c8acddf..4ecf430 100644 --- a/tests/min_msg/msg.rs +++ b/tests/min_msg/msg.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Msg`](evident::event::Msg) trait. //! -//! [qa.ux.usage], [event.msg] +//! [req:qa.ux.usage], [req:event.msg] /// Struct used for a minimal [`Msg`](evident::event::Msg) trait implementation. #[derive(Debug, Clone, PartialEq, Eq)] diff --git a/tests/pub_sub/set_events.rs b/tests/pub_sub/set_events.rs index cf53d66..6eedc11 100644 --- a/tests/pub_sub/set_events.rs +++ b/tests/pub_sub/set_events.rs @@ -8,7 +8,7 @@ use crate::pub_sub::setup::{ entry::MinEventEntry, id::MinId, interim_event::MinInterimEvent, TESTS_PUBLISHER, }; -/// [event.origin.test.basic] +/// [req:event.origin.test.basic] #[test] fn set_event_has_correct_origin() { let id = MinId { id: 1 }; @@ -52,7 +52,7 @@ fn set_event_has_correct_origin() { ); } -/// [event.origin.test.two_origins] +/// [req:event.origin.test.two_origins] #[test] fn set_same_event_twice_with_different_origin() { let id = MinId { id: 1 }; @@ -104,7 +104,7 @@ fn set_same_event_twice_with_different_origin() { ); } -/// [event.origin.test.same_origin] +/// [req:event.origin.test.same_origin] #[test] fn set_same_event_twice_with_same_origin() { let id = MinId { id: 1 }; @@ -152,7 +152,7 @@ fn set_same_event_twice_with_same_origin() { assert_ne!(event_1, event_2, "Received events are equal."); } -/// [subs.test.mult_subs] +/// [req:subs.test.mult_subs] #[test] fn set_event_received_exactly_once_per_receiver() { let id = MinId { id: 1 }; diff --git a/tests/pub_sub/subscription.rs b/tests/pub_sub/subscription.rs index 8ba0efa..9d5d282 100644 --- a/tests/pub_sub/subscription.rs +++ b/tests/pub_sub/subscription.rs @@ -131,7 +131,7 @@ fn subscribe_to_two_ids_at_once() { ); } -/// [cap.test.mult] +/// [req:cap.test.mult] #[test] fn receiver_for_all_events_two_events_set() { let id_1 = MinId { id: 1 }; diff --git a/tests/pub_sub/threading.rs b/tests/pub_sub/threading.rs index 971fbc9..ad0ca77 100644 --- a/tests/pub_sub/threading.rs +++ b/tests/pub_sub/threading.rs @@ -164,7 +164,7 @@ fn set_events_in_many_threads() { } } -/// [pub.threaded.test] +/// [req:pub.threaded.test] #[test] fn set_events_in_many_threads_for_one_subscriber() { // Note: This value should be at least 2x lower than the channel bounds set for the publisher. diff --git a/tests/public_concretise/entry.rs b/tests/public_concretise/entry.rs index ed276ad..135ecf2 100644 --- a/tests/public_concretise/entry.rs +++ b/tests/public_concretise/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/public_concretise/id.rs b/tests/public_concretise/id.rs index 348f389..b2c777a 100644 --- a/tests/public_concretise/id.rs +++ b/tests/public_concretise/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/public_concretise/interim_event.rs b/tests/public_concretise/interim_event.rs index 2641405..0186ef1 100644 --- a/tests/public_concretise/interim_event.rs +++ b/tests/public_concretise/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/public_concretise/mod.rs b/tests/public_concretise/mod.rs index 51f2612..bf60d47 100644 --- a/tests/public_concretise/mod.rs +++ b/tests/public_concretise/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and public publisher. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use crate::public_concretise::public_publisher::PUB_PUBLISHER; diff --git a/tests/public_concretise/public_publisher.rs b/tests/public_concretise/public_publisher.rs index 0d8882e..a44827d 100644 --- a/tests/public_concretise/public_publisher.rs +++ b/tests/public_concretise/public_publisher.rs @@ -1,7 +1,7 @@ //! This module creates a public [`EvidentPublisher`](evident::publisher::EvidentPublisher), //! and the `set_event!()` macros for this publisher. //! -//! [qa.ux.usage] +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; From b34c14d333e053fbd0c71f4a4814b2df35c24541 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 16 Aug 2023 10:41:25 +0200 Subject: [PATCH 23/37] fix: relative doc-link --- src/event/entry.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/event/entry.rs b/src/event/entry.rs index 6d9469a..3da55ca 100644 --- a/src/event/entry.rs +++ b/src/event/entry.rs @@ -7,10 +7,10 @@ use std::hash::Hash; use super::{origin::Origin, Id, Msg}; /// Trait that must be implemented for a custom *evident* event-entry.\ -/// This implementation must then be used for implementations of the traits [`EventEntry`] and [`IntermediaryEvent`].\ +/// This implementation must then be used for implementations of the traits [`EventEntry`] and [`IntermediaryEvent`](super::intermediary::IntermediaryEvent).\ /// All implementations are needed to create an *evident* publisher using the [`create_static_publisher!()`](crate::create_static_publisher) macro. /// -/// The optional [`Filter`](self::filter::Filter) trait must also use the same implementation of this [`Id`] trait. +/// The optional [`Filter`](super::filter::Filter) trait must also use the same implementation of this [`Id`] trait. /// /// **Note:** Since it is a trait, the custom implementation may contain additional fields and functions. /// From 28af97d264c95946ac5feec3f97bb5f679a84a57 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 16 Aug 2023 10:44:22 +0200 Subject: [PATCH 24/37] fix: change highlighting of macro-samples --- src/creation_macros.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/creation_macros.rs b/src/creation_macros.rs index 11e0421..6c323e7 100644 --- a/src/creation_macros.rs +++ b/src/creation_macros.rs @@ -7,7 +7,7 @@ /// In the following example, text between `<>` is used as placeholder.\ /// The visibility setting at the beginning is also **optional**. /// -/// ```ignore +/// ```text /// evident::create_static_publisher!( /// , /// id_type = , @@ -25,7 +25,7 @@ /// /// **Example without filter:** /// -/// ```ignore +/// ```text /// evident::create_static_publisher!( /// pub MY_PUBLISHER, /// id_type = MyId, @@ -41,7 +41,7 @@ /// /// **Example with filter:** /// -/// ```ignore +/// ```text /// evident::create_static_publisher!( /// pub MY_PUBLISHER, /// id_type = MyId, @@ -254,7 +254,7 @@ macro_rules! z__create_static_publisher { /// /// Note: Set fully qualified paths for the types to make the macro accessible from anywhere. /// -/// ```ignore +/// ```text /// evident::create_set_event_macro!( /// id_type = , /// entry_type = , @@ -264,7 +264,7 @@ macro_rules! z__create_static_publisher { /// /// **Example with dummy implementations:** /// -/// ```ignore +/// ```text /// evident::create_set_event_macro!( /// id_type = my_crate::my_mod::MyId, /// entry_type = my_crate::my_mod::MyEventEntry, @@ -274,7 +274,7 @@ macro_rules! z__create_static_publisher { /// /// **Example with no export:** /// -/// ```ignore +/// ```text /// evident::create_set_event_macro!( /// no_export, /// id_type = my_crate::my_mod::MyId, From bc2cc3d34d390666815bc9c2b9cb494d328b3fcb Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 16 Aug 2023 10:46:26 +0200 Subject: [PATCH 25/37] fix: hide internal macros from doc --- src/creation_macros.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/creation_macros.rs b/src/creation_macros.rs index 6c323e7..68fc42b 100644 --- a/src/creation_macros.rs +++ b/src/creation_macros.rs @@ -118,6 +118,7 @@ macro_rules! create_static_publisher { /// Internal macro to set up a static publisher. /// /// **Note:** Use [`create_static_publisher`](crate::create_static_publisher) instead. +#[doc(hidden)] #[macro_export] macro_rules! z__setup_static_publisher { ($publisher_name:ident, @@ -189,6 +190,7 @@ macro_rules! z__setup_static_publisher { /// Internal macro to create a static publisher. /// /// **Note:** Use [`create_static_publisher`](crate::create_static_publisher) instead. +#[doc(hidden)] #[macro_export] macro_rules! z__create_static_publisher { ($publisher_name:ident, From 90a6c7f9a0268015e62d2722965dd7fedbbde99d Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Fri, 18 Aug 2023 12:51:36 +0200 Subject: [PATCH 26/37] fix: hide internals from doc --- src/publisher.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/publisher.rs b/src/publisher.rs index 5e049f3..46780da 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -86,8 +86,6 @@ type Capturer = SyncSender>; /// An **EvidentPublisher** is used to capture, publish, and manage subscriptions. /// -/// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. -/// /// [req:pub] pub struct EvidentPublisher where @@ -150,6 +148,8 @@ where { /// Create a new [`EvidentPublisher`], and spawn a new event handler thread for events captured by the publisher. /// + /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. + /// /// [req:pub] fn create( mut on_event: impl FnMut(Event) + std::marker::Send + 'static, @@ -195,6 +195,8 @@ where /// Create a new [`EvidentPublisher`] without an event filter. /// + /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. + /// /// [req:pub] pub fn new( on_event: impl FnMut(Event) + std::marker::Send + 'static, @@ -215,6 +217,8 @@ where /// Create a new [`EvidentPublisher`] with an event filter. /// + /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. + /// /// [req:pub], [req:cap.filter] pub fn with( on_event: impl FnMut(Event) + std::marker::Send + 'static, @@ -265,6 +269,7 @@ where /// **Note:** This function should **not** be called manually, because it is automatically called on `drop()` of an intermediary event. /// /// [req:cap] + #[doc(hidden)] pub fn _capture>(&self, interm_event: &mut I) { let entry = interm_event.take_entry(); @@ -441,6 +446,7 @@ where /// **Note:** This function should **not** be called manually, because it is already called in the event handler. /// /// [req:cap] + #[doc(hidden)] pub fn on_event(&self, event: Event) { let arc_event = Arc::new(event); let key = arc_event.entry.get_event_id(); From 3ee065ce449e218f118ff5d3b66a434040b85b79 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Mon, 21 Aug 2023 11:18:22 +0200 Subject: [PATCH 27/37] fix: update wiki links for requirement- IDs --- src/publisher.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/publisher.rs b/src/publisher.rs index 46780da..48794d4 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -16,7 +16,7 @@ use crate::{ /// Trait to implement for [`Id`], to control the publisher and all listeners. /// -/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrl-control-capturing) +/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl) pub trait CaptureControl { /// Returns `true` if the given [`Id`] is used to signal the start of event capturing. /// @@ -183,7 +183,7 @@ where any_event: Arc::new(RwLock::new(HashMap::new())), capturer: send, filter, - // [req:cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5.a-REQact-cap.ctrl#capctrlinit-initial-capturing-state) + // [req:cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.init) capturing: Arc::new(AtomicBool::new(true)), capture_blocking: mode, capture_channel_bound, From aa68ba2f913f0b52946b734e56dfaded67662aab Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Mon, 21 Aug 2023 13:33:10 +0200 Subject: [PATCH 28/37] fix: adapt DoD for PR template --- .github/pull_request_template.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index bed902a..3f27e66 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,30 @@ # List of issues that this PR closes +[[ + e.g. closes #1 closes #2 … -# General "Definition of Done" ([req:qa.DoD]) +]] + +# Definition of Done ([req:qa.DoD]) **Please consider the following requirements:** -- [ ] Add/Update requirement tags (see: [req:qa.links]) +- [ ] Add/Update requirement references (see: [req:qa.links]) - [ ] Add usage examples in doc-comments (see: [req:qa.ux.usage]) - [ ] Only use macros if they improve *evident's* usability (see: [req:qa.ux.macros]) - [ ] Prefer `RwLock` over `Mutex` (see: [req:qa.perf.locks]) **Note:** You may ignore requirements that are not relevant to your PR. -# Describe how you fixed the issue(s) +# Decisions you made for this PR + +{{ + +Add a clear and concise description about your decisions related to this PR. + +**Note:** May be omitted if decisions are documented in committed files. + +**Note:** Decisions may be added to the "Decision Records" section in the wiki. -Add a clear and concise description about how you fixed the issue(s). +}} From 4a8af4593e523f4a806f2a8ef587dd186c7c0939 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Mon, 21 Aug 2023 17:18:17 +0200 Subject: [PATCH 29/37] fix: replace renamed req-id --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3f27e66..ba66ca1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,7 +10,7 @@ e.g. closes #1 closes #2 … **Please consider the following requirements:** -- [ ] Add/Update requirement references (see: [req:qa.links]) +- [ ] Add/Update requirement references (see: [req:qa.tracing]) - [ ] Add usage examples in doc-comments (see: [req:qa.ux.usage]) - [ ] Only use macros if they improve *evident's* usability (see: [req:qa.ux.macros]) - [ ] Prefer `RwLock` over `Mutex` (see: [req:qa.perf.locks]) From 159b634a550f90640e5332df3daf7eaaacea7713 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Thu, 31 Aug 2023 17:20:27 +0200 Subject: [PATCH 30/37] chore: add wiki-links to references --- .github/pull_request_template.md | 10 ++-- .github/workflows/rust.yml | 14 +++--- .hooks/commit-msg | 2 +- src/creation_macros.rs | 8 +-- src/event/entry.rs | 16 +++--- src/event/mod.rs | 24 ++++----- src/event/origin.rs | 6 +-- src/publisher.rs | 56 ++++++++++----------- src/subscription.rs | 8 +-- tests/min_concretise/entry.rs | 2 +- tests/min_concretise/id.rs | 6 +-- tests/min_concretise/interim_event.rs | 2 +- tests/min_concretise/mod.rs | 4 +- tests/min_filter/entry.rs | 2 +- tests/min_filter/filter.rs | 2 +- tests/min_filter/id.rs | 2 +- tests/min_filter/interim_event.rs | 2 +- tests/min_filter/mod.rs | 2 +- tests/min_msg/entry.rs | 2 +- tests/min_msg/id.rs | 2 +- tests/min_msg/interim_event.rs | 2 +- tests/min_msg/mod.rs | 2 +- tests/min_msg/msg.rs | 2 +- tests/pub_sub/set_events.rs | 8 +-- tests/pub_sub/subscription.rs | 2 +- tests/pub_sub/threading.rs | 2 +- tests/public_concretise/entry.rs | 2 +- tests/public_concretise/id.rs | 2 +- tests/public_concretise/interim_event.rs | 2 +- tests/public_concretise/mod.rs | 2 +- tests/public_concretise/public_publisher.rs | 2 +- 31 files changed, 100 insertions(+), 100 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ba66ca1..3b450a7 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,14 +6,14 @@ e.g. closes #1 closes #2 … ]] -# Definition of Done ([req:qa.DoD]) +# Definition of Done ([req:qa.DoD](https://github.com/mhatzl/evident/wiki/5-REQ-qa.DoD#qadod-have-a-definition-of-done-for-requirements)) **Please consider the following requirements:** -- [ ] Add/Update requirement references (see: [req:qa.tracing]) -- [ ] Add usage examples in doc-comments (see: [req:qa.ux.usage]) -- [ ] Only use macros if they improve *evident's* usability (see: [req:qa.ux.macros]) -- [ ] Prefer `RwLock` over `Mutex` (see: [req:qa.perf.locks]) +- [ ] Add/Update requirement references (see: [req:qa.tracing](https://github.com/mhatzl/evident/wiki/5-REQ-qa.tracing#qatracing-use-requirement-ids-in-the-evident-repository)) +- [ ] Add usage examples in doc-comments (see: [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples)) +- [ ] Only use macros if they improve *evident's* usability (see: [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability)) +- [ ] Prefer `RwLock` over `Mutex` (see: [req:qa.perf.locks](https://github.com/mhatzl/evident/wiki/5-REQ-qa.perf.locks#qaperflocks-performance-impact-of-multithreaded-locking)) **Note:** You may ignore requirements that are not relevant to your PR. diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index a538c25..6654b2c 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -10,7 +10,7 @@ env: CARGO_TERM_COLOR: always jobs: - # [req:qa.pipeline.1_style] + # [req:qa.pipeline.1_style](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.1_style#qapipeline1_style-ensure-consistent-formatting) format: name: Check Formatting runs-on: ubuntu-latest @@ -20,11 +20,11 @@ jobs: - name: Run cargo fmt run: cargo fmt -- --check - # [req:qa.pipeline.2_lint] + # [req:qa.pipeline.2_lint](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.2_lint#qapipeline2_lint-ensure-good-coding-standard) lint: name: Run Linter (clippy) runs-on: ubuntu-latest - # [req:qa.sustain] + # [req:qa.sustain](https://github.com/mhatzl/evident/wiki/5-REQ-qa.sustain#qasustain-consider-sustainability-during-design-and-development) needs: format steps: @@ -32,11 +32,11 @@ jobs: - name: Run linter run: cargo clippy -- -D warnings - # [req:qa.pipeline.3_build] + # [req:qa.pipeline.3_build](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.3_build#qapipeline3_build-ensure-evident-builds) build: name: Run Build runs-on: ubuntu-latest - # [req:qa.sustain] + # [req:qa.sustain](https://github.com/mhatzl/evident/wiki/5-REQ-qa.sustain#qasustain-consider-sustainability-during-design-and-development) needs: lint steps: @@ -44,11 +44,11 @@ jobs: - name: Build run: cargo build --verbose - # [req:qa.pipeline.4_tests] + # [req:qa.pipeline.4_tests](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.4_tests#qapipeline4_tests-ensure-tests-still-pass) test: name: Run Tests runs-on: ubuntu-latest - # [req:qa.sustain] + # [req:qa.sustain](https://github.com/mhatzl/evident/wiki/5-REQ-qa.sustain#qasustain-consider-sustainability-during-design-and-development) needs: build steps: diff --git a/.hooks/commit-msg b/.hooks/commit-msg index d08e0bf..4a1f6a2 100644 --- a/.hooks/commit-msg +++ b/.hooks/commit-msg @@ -46,4 +46,4 @@ fi if ! head -1 "$1" | grep -qE "^.{1,50}$"; then echo -e "${YELLOW}\nWARNING: ': ' should not have more than 50 characters!${CLEAR}\n" >&2 print_help false -fi \ No newline at end of file +fi diff --git a/src/creation_macros.rs b/src/creation_macros.rs index 68fc42b..8f628bd 100644 --- a/src/creation_macros.rs +++ b/src/creation_macros.rs @@ -57,7 +57,7 @@ /// ); /// ``` /// -/// [req:qa.ux.macros] +/// [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) #[macro_export] macro_rules! create_static_publisher { ($publisher_name:ident, @@ -285,7 +285,7 @@ macro_rules! z__create_static_publisher { /// ); /// ``` /// -/// [req:qa.ux.macros] +/// [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) #[macro_export] macro_rules! create_set_event_macro { (id_type = $id_t:ty, @@ -315,7 +315,7 @@ macro_rules! create_set_event_macro { /// set_event!(id, msg).finalize(); /// ``` /// - /// [req:event.set], [req:qa.ux.macros] + /// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) #[macro_export] macro_rules! set_event { ($id:expr) => { @@ -361,7 +361,7 @@ macro_rules! create_set_event_macro { /// set_event!(id, msg).finalize(); /// ``` /// - /// [req:event.set], [req:qa.ux.macros] + /// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) macro_rules! set_event { ($id:expr) => { $crate::event::set_event::<$id_t, $msg_t, $entry_t, $interm_event_t>( diff --git a/src/event/entry.rs b/src/event/entry.rs index 3da55ca..b0989e5 100644 --- a/src/event/entry.rs +++ b/src/event/entry.rs @@ -1,6 +1,6 @@ //! Contains the [`EventEntry] trait. //! -//! [req:event.entry] +//! [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry) use std::hash::Hash; @@ -14,7 +14,7 @@ use super::{origin::Origin, Id, Msg}; /// /// **Note:** Since it is a trait, the custom implementation may contain additional fields and functions. /// -/// [req:event.entry], [req:event.entry.generic] +/// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry), [req:event.entry.generic](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry.generic#evententrygeneric-generic-event-entry) pub trait EventEntry: Default + Clone + Hash + Send + Sync + 'static { /// Creates a new [`EventEntry`]. /// @@ -26,32 +26,32 @@ pub trait EventEntry: Default + Clone + Hash + Send + Sync + 'sta /// * `msg` ... Optional main event message /// * `origin` ... The [`Origin`] the event was set at /// - /// [req:event.entry], [req:event.id], [req:event.msg], [req:event.origin] + /// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry), [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier), [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message), [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) fn new(event_id: K, msg: Option>, origin: Origin) -> Self; /// Returns the [`Id`] of this event. /// - /// [req:event.id] + /// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier) fn get_event_id(&self) -> &K; /// Convert this [`EventEntry`] into the [`Id`] of this event. /// - /// [req:event.id] + /// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier) fn into_event_id(self) -> K; /// Get the entry-ID that was generated when the event was set. /// - /// [req:event.entry.id] + /// [req:event.entry.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry.id#evententryid-unique-event-entry) fn get_entry_id(&self) -> crate::uuid::Uuid; /// Get the main message that was given when the event was set, /// or `None` if no message was given. /// - /// [req:event.msg] + /// [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) fn get_msg(&self) -> Option<&M>; /// Get the [`Origin`] the event was set at. /// - /// [req:event.origin] + /// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) fn get_origin(&self) -> &Origin; } diff --git a/src/event/mod.rs b/src/event/mod.rs index 865c8f7..00fa68f 100644 --- a/src/event/mod.rs +++ b/src/event/mod.rs @@ -1,6 +1,6 @@ //! Contains the *evident* [`Event`], and all related traits, structures, and functions. //! -//! [req:event] +//! [req:event](https://github.com/mhatzl/evident/wiki/5-REQ-event#event-structure-of-an-evident-event) use std::marker::PhantomData; @@ -18,7 +18,7 @@ pub mod origin; /// /// The optional [`Filter`](self::filter::Filter) trait must also use the same implementation of this [`Id`] trait. /// -/// [req:event.id], [req:event.id.generic] +/// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier), [req:event.id.generic](https://github.com/mhatzl/evident/wiki/5-REQ-event.id.generic#eventidgeneric-generic-event-id) pub trait Id: core::fmt::Debug + Default + Clone + std::hash::Hash + PartialEq + Eq + Send + Sync + 'static { @@ -32,7 +32,7 @@ pub trait Id: /// /// **Note:** This trait is already implemented for [`String`]. /// -/// [req:event.msg] +/// [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) pub trait Msg: core::fmt::Debug + Clone + Send + Sync + 'static {} impl Msg for String {} @@ -46,7 +46,7 @@ impl Msg for String {} /// * `msg` ... Main message that is set for this event /// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) /// -/// [req:event.set], [req:event.origin] +/// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) pub fn set_event_with_msg, I: IntermediaryEvent>( event_id: K, msg: impl Into, @@ -63,7 +63,7 @@ pub fn set_event_with_msg, I: IntermediaryEve /// * `event_id` ... The [`Id`] used for this event /// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) /// -/// [req:event.set], [req:event.origin] +/// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) pub fn set_event, I: IntermediaryEvent>( event_id: K, origin: Origin, @@ -74,7 +74,7 @@ pub fn set_event, I: IntermediaryEvent where @@ -84,7 +84,7 @@ where { /// [`EventEntry`] of the event. /// - /// [req:event.entry] + /// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry) pub(crate) entry: T, // PahmtomData needed for unused generics @@ -120,21 +120,21 @@ impl> Event { /// Returns the [`Id`] of this event. /// - /// [req:event.id] + /// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier) pub fn get_event_id(&self) -> &K { self.entry.get_event_id() } /// Returns the [`EventEntry`] of this event. /// - /// [req:event.entry] + /// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry) pub fn get_entry(&self) -> &T { &self.entry } /// Get the entry-ID that was generated when the event was set. /// - /// [req:event.entry.id] + /// [req:event.entry.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry.id#evententryid-unique-event-entry) pub fn get_entry_id(&self) -> crate::uuid::Uuid { self.entry.get_entry_id() } @@ -142,14 +142,14 @@ impl> Event { /// Get the main message that was given when the event was set, /// or `None` if no message was given. /// - /// [req:event.msg] + /// [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) pub fn get_msg(&self) -> Option<&M> { self.entry.get_msg() } /// Get the [`Origin`] the event was set at. /// - /// [req:event.origin] + /// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) pub fn get_origin(&self) -> &Origin { self.entry.get_origin() } diff --git a/src/event/origin.rs b/src/event/origin.rs index 8e12bbf..6bfa8f6 100644 --- a/src/event/origin.rs +++ b/src/event/origin.rs @@ -3,7 +3,7 @@ /// Structure to point to a location in the program code. /// It is used to know where the event was set, but may be used for other use cases aswell. /// -/// [req:event.origin] +/// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) #[derive(Debug, Default, PartialEq, Eq, Clone)] pub struct Origin { /// Module path to the code location. @@ -31,7 +31,7 @@ impl Origin { /// * `filename` ... Filename where the code is located /// * `line_nr` ... Line number where the code is located /// - /// [req:event.origin] + /// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) pub fn new(module_path: &'static str, filename: &'static str, line_nr: u32) -> Self { Origin { module_path, @@ -59,7 +59,7 @@ impl core::fmt::Display for Origin { /// Convenience wrapper to create an [`Origin`] for the code position this macro is used at. /// -/// [req:event.origin], [req:qa.ux.macros] +/// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin), [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) #[macro_export] macro_rules! this_origin { () => { diff --git a/src/publisher.rs b/src/publisher.rs index 48794d4..b7acc8a 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -26,12 +26,12 @@ pub trait CaptureControl { /// id == &START_CAPTURING_ID /// ``` /// - /// [req:cap.ctrl.start] + /// [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) fn start(id: &Self) -> bool; /// Returns the *start-ID*. /// - /// [req:cap.ctrl.start] + /// [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) fn start_id() -> Self; /// Returns `true` if the given [`Id`] is used to signal the end of event capturing. @@ -42,18 +42,18 @@ pub trait CaptureControl { /// id == &STOP_CAPTURING_ID /// ``` /// - /// [req:cap.ctrl.stop] + /// [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) fn stop(id: &Self) -> bool; /// Returns the *stop-ID*. /// - /// [req:cap.ctrl.stop] + /// [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) fn stop_id() -> Self; } /// Returns `true` if the given [`Id`] is used to control capturing. /// -/// [req:cap.ctrl] +/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl#capctrl-control-capturing) pub fn is_control_id(id: &impl CaptureControl) -> bool { CaptureControl::stop(id) || CaptureControl::start(id) } @@ -86,7 +86,7 @@ type Capturer = SyncSender>; /// An **EvidentPublisher** is used to capture, publish, and manage subscriptions. /// -/// [req:pub] +/// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing) pub struct EvidentPublisher where K: Id + CaptureControl, @@ -96,27 +96,27 @@ where { /// The hashmap of subscribers listening to specific events. /// - /// [req:subs.specific] + /// [req:subs.specific](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific#subsspecific-subscribe-to-specific-events) pub(crate) subscriptions: Arc>>, /// The hashmap of subscribers listening to all events. /// - /// [req:subs.all] + /// [req:subs.all](https://github.com/mhatzl/evident/wiki/5-REQ-subs.all#subsall-subscribe-to-all-events) pub(crate) any_event: Arc>>, /// The send-part of the capturing channel. /// - /// [req:cap] + /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) pub(crate) capturer: Capturer, /// Optional filter that is applied when capturing events. /// - /// [req:cap.filter] + /// [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) filter: Option, /// Flag to control if capturing is active or inactive. /// - /// [req:cap.ctrl] + /// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl#capctrl-control-capturing) capturing: Arc, /// Flag to control the capture mode. @@ -124,12 +124,12 @@ where /// Defines the size of the capturing send-buffer. /// - /// [req:cap] + /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) capture_channel_bound: usize, /// Defines the size of each subscription send-buffer. /// - /// [req:subs] + /// [req:subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#subs-subscribing-to-events) subscription_channel_bound: usize, /// Number of missed captures in *non-blocking* capture mode. @@ -150,7 +150,7 @@ where /// /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. /// - /// [req:pub] + /// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing) fn create( mut on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: Option, @@ -162,7 +162,7 @@ where let (send, recv): (SyncSender>, _) = mpsc::sync_channel(capture_channel_bound); - // [req:pub.threaded] + // [req:pub.threaded](https://github.com/mhatzl/evident/wiki/5-REQ-pub.threaded#pubthreaded-multithreaded-publishing) thread::spawn(move || { while let Ok(mut event) = recv.recv() { if timestamp_kind == EventTimestampKind::Captured { @@ -197,7 +197,7 @@ where /// /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. /// - /// [req:pub] + /// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing) pub fn new( on_event: impl FnMut(Event) + std::marker::Send + 'static, capture_mode: CaptureMode, @@ -219,7 +219,7 @@ where /// /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. /// - /// [req:pub], [req:cap.filter] + /// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing), [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) pub fn with( on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: F, @@ -240,14 +240,14 @@ where /// Returns the event filter, or `None` if no filter is set. /// - /// [req:cap.filter] + /// [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) pub fn get_filter(&self) -> &Option { &self.filter } /// Returns `true` if the given event-entry passes the filter, or the event-ID is a control-ID. /// - /// [req:cap.filter] + /// [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) pub fn entry_allowed(&self, entry: &impl EventEntry) -> bool { if !is_control_id(entry.get_event_id()) { if !self.capturing.load(Ordering::Acquire) { @@ -268,12 +268,12 @@ where /// /// **Note:** This function should **not** be called manually, because it is automatically called on `drop()` of an intermediary event. /// - /// [req:cap] + /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) #[doc(hidden)] pub fn _capture>(&self, interm_event: &mut I) { let entry = interm_event.take_entry(); - // [req:cap.filter] + // [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) if !self.entry_allowed(&entry) { return; } @@ -332,7 +332,7 @@ where /// Returns a subscription to events with the given event-ID, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [req:subs.specific.one] + /// [req:subs.specific.one](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.one#subsspecificone-subscribe-to-one-specific-event) pub fn subscribe(&self, id: K) -> Result, SubscriptionError> { self.subscribe_to_many(vec![id]) } @@ -340,7 +340,7 @@ where /// Returns a subscription to events with the given event-IDs, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [req:subs.specific.mult] + /// [req:subs.specific.mult](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.mult#subsspecificmult-subscribe-to-multiple-specific-events) pub fn subscribe_to_many( &self, ids: Vec, @@ -383,7 +383,7 @@ where /// Returns a subscription to all events, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [req:subs.all] + /// [req:subs.all](https://github.com/mhatzl/evident/wiki/5-REQ-subs.all#subsall-subscribe-to-all-events) pub fn subscribe_to_all_events( &self, ) -> Result, SubscriptionError> { @@ -410,7 +410,7 @@ where /// Returns `true` if capturing is *active*. /// - /// [req:cap.ctrl.info] + /// [req:cap.ctrl.info](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.info#capctrlinfo-get-capturing-state) pub fn is_capturing(&self) -> bool { self.capturing.load(Ordering::Acquire) } @@ -419,7 +419,7 @@ where /// /// **Note:** Capturing is already started initially, so this function is only needed after manually stopping capturing. /// - /// [req:cap.ctrl.start] + /// [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) pub fn start(&self) { let empty_msg: Option = None; let start_event = Event::new(EventEntry::new(K::start_id(), empty_msg, this_origin!())); @@ -431,7 +431,7 @@ where /// Stop capturing. /// - /// [req:cap.ctrl.stop] + /// [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) pub fn stop(&self) { let empty_msg: Option = None; let stop_event = Event::new(EventEntry::new(K::stop_id(), empty_msg, this_origin!())); @@ -445,7 +445,7 @@ where /// /// **Note:** This function should **not** be called manually, because it is already called in the event handler. /// - /// [req:cap] + /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) #[doc(hidden)] pub fn on_event(&self, event: Event) { let arc_event = Arc::new(event); diff --git a/src/subscription.rs b/src/subscription.rs index 22d1333..d38eb06 100644 --- a/src/subscription.rs +++ b/src/subscription.rs @@ -14,7 +14,7 @@ use crate::{ /// Subscription that is returned when subscribing to events captured by an [`EvidentPublisher`]. /// -///[req:subs] +///[req:subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#subs-subscribing-to-events) pub struct Subscription<'p, K, M, T, F> where K: Id + CaptureControl, @@ -134,7 +134,7 @@ where /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events /// - /// [req:subs.specific.one] + /// [req:subs.specific.one](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.one#subsspecificone-subscribe-to-one-specific-event) pub fn subscribe_id(&mut self, id: K) -> Result<(), SubscriptionError> { self.subscribe_many(vec![id]) } @@ -154,7 +154,7 @@ where /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events /// - /// [req:subs.specific.mult] + /// [req:subs.specific.mult](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.mult#subsspecificmult-subscribe-to-multiple-specific-events) pub fn subscribe_many(&mut self, ids: Vec) -> Result<(), SubscriptionError> { if self.sub_to_all || self.subscriptions.is_none() { return Err(SubscriptionError::AllEventsSubscriptionNotModifiable); @@ -305,7 +305,7 @@ pub enum SubscriptionError { /// *Sender-part* of the subscription-channel between a [`Subscription`] and an [`EvidentPublisher`]. /// -/// [req:subs] +/// [req:subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#subs-subscribing-to-events) #[derive(Clone)] pub(crate) struct SubscriptionSender where diff --git a/tests/min_concretise/entry.rs b/tests/min_concretise/entry.rs index 2c15175..dca389f 100644 --- a/tests/min_concretise/entry.rs +++ b/tests/min_concretise/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_concretise/id.rs b/tests/min_concretise/id.rs index 09a8011..62462ba 100644 --- a/tests/min_concretise/id.rs +++ b/tests/min_concretise/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) /// Struct used for a minimal [`Id`](evident::event::Id) trait implementation. #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] @@ -12,12 +12,12 @@ impl evident::event::Id for MinId {} /// Event-ID to notify the publisher and all listeners that capturing should be started. /// -/// [req:event.id.ctrl], [req:cap.ctrl.start] +/// [req:event.id.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-event.id.ctrl#eventidctrl-event-ids-for-capture-control), [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) const START_CAPTURING: MinId = MinId { id: -1 }; /// Event-ID to notify the publisher and all listeners that capturing should be stopped. /// -/// [req:event.id.ctrl], [req:cap.ctrl.stop] +/// [req:event.id.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-event.id.ctrl#eventidctrl-event-ids-for-capture-control), [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) const STOP_CAPTURING: MinId = MinId { id: -2 }; impl evident::publisher::CaptureControl for MinId { diff --git a/tests/min_concretise/interim_event.rs b/tests/min_concretise/interim_event.rs index 6b5ac12..ace694c 100644 --- a/tests/min_concretise/interim_event.rs +++ b/tests/min_concretise/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_concretise/mod.rs b/tests/min_concretise/mod.rs index b7e9dcf..b6da364 100644 --- a/tests/min_concretise/mod.rs +++ b/tests/min_concretise/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident*. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::publisher::{CaptureMode, EventTimestampKind}; @@ -34,7 +34,7 @@ evident::create_set_event_macro!( /// Test using the minimal pub/sub implementation to set and listen to an event. /// -/// [req:cap.test.recv] +/// [req:cap.test.recv](https://github.com/mhatzl/evident/wiki/5-REQ-cap#captestrecv-captured-event-received-by-a-subscriber) #[test] fn setup_minimal_publisher() { let some_id = MinId { id: 3 }; diff --git a/tests/min_filter/entry.rs b/tests/min_filter/entry.rs index 135ecf2..b40f171 100644 --- a/tests/min_filter/entry.rs +++ b/tests/min_filter/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_filter/filter.rs b/tests/min_filter/filter.rs index 32823e4..2907356 100644 --- a/tests/min_filter/filter.rs +++ b/tests/min_filter/filter.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Filter`] trait. //! -//! [req:qa.ux.usage], [req:cap.filter] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples), [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) use evident::event::filter::Filter; diff --git a/tests/min_filter/id.rs b/tests/min_filter/id.rs index 06261fe..cd718f5 100644 --- a/tests/min_filter/id.rs +++ b/tests/min_filter/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/min_filter/interim_event.rs b/tests/min_filter/interim_event.rs index 0186ef1..6295ac2 100644 --- a/tests/min_filter/interim_event.rs +++ b/tests/min_filter/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_filter/mod.rs b/tests/min_filter/mod.rs index 34998e5..e2faa31 100644 --- a/tests/min_filter/mod.rs +++ b/tests/min_filter/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and [`Filter`](evident::event::filter::Filter). //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::publisher::{CaptureMode, EventTimestampKind}; diff --git a/tests/min_msg/entry.rs b/tests/min_msg/entry.rs index 430f74c..6e07ae2 100644 --- a/tests/min_msg/entry.rs +++ b/tests/min_msg/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_msg/id.rs b/tests/min_msg/id.rs index b2c777a..aa1274e 100644 --- a/tests/min_msg/id.rs +++ b/tests/min_msg/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/min_msg/interim_event.rs b/tests/min_msg/interim_event.rs index 8f5b33b..733c050 100644 --- a/tests/min_msg/interim_event.rs +++ b/tests/min_msg/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_msg/mod.rs b/tests/min_msg/mod.rs index 411d540..83cc91f 100644 --- a/tests/min_msg/mod.rs +++ b/tests/min_msg/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and a custom [`Msg`](evident::event::Msg). //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::publisher::{CaptureMode, EventTimestampKind}; diff --git a/tests/min_msg/msg.rs b/tests/min_msg/msg.rs index 4ecf430..c93b6e7 100644 --- a/tests/min_msg/msg.rs +++ b/tests/min_msg/msg.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Msg`](evident::event::Msg) trait. //! -//! [req:qa.ux.usage], [req:event.msg] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples), [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) /// Struct used for a minimal [`Msg`](evident::event::Msg) trait implementation. #[derive(Debug, Clone, PartialEq, Eq)] diff --git a/tests/pub_sub/set_events.rs b/tests/pub_sub/set_events.rs index 6eedc11..4ee4da1 100644 --- a/tests/pub_sub/set_events.rs +++ b/tests/pub_sub/set_events.rs @@ -8,7 +8,7 @@ use crate::pub_sub::setup::{ entry::MinEventEntry, id::MinId, interim_event::MinInterimEvent, TESTS_PUBLISHER, }; -/// [req:event.origin.test.basic] +/// [req:event.origin.test.basic](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigintestbasic-origin-of-set-event-points-to-set_event-call) #[test] fn set_event_has_correct_origin() { let id = MinId { id: 1 }; @@ -52,7 +52,7 @@ fn set_event_has_correct_origin() { ); } -/// [req:event.origin.test.two_origins] +/// [req:event.origin.test.two_origins](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigintesttwo_origins-origin-of-an-event-set-with-two-set_event-calls-differs) #[test] fn set_same_event_twice_with_different_origin() { let id = MinId { id: 1 }; @@ -104,7 +104,7 @@ fn set_same_event_twice_with_different_origin() { ); } -/// [req:event.origin.test.same_origin] +/// [req:event.origin.test.same_origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigintestsame_origin-set-origin-of-an-event-manually-for-two-set_event_with_msg-calls) #[test] fn set_same_event_twice_with_same_origin() { let id = MinId { id: 1 }; @@ -152,7 +152,7 @@ fn set_same_event_twice_with_same_origin() { assert_ne!(event_1, event_2, "Received events are equal."); } -/// [req:subs.test.mult_subs] +/// [req:subs.test.mult_subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#substestmult_subs-multiple-subscribers-to-same-event) #[test] fn set_event_received_exactly_once_per_receiver() { let id = MinId { id: 1 }; diff --git a/tests/pub_sub/subscription.rs b/tests/pub_sub/subscription.rs index 9d5d282..efed867 100644 --- a/tests/pub_sub/subscription.rs +++ b/tests/pub_sub/subscription.rs @@ -131,7 +131,7 @@ fn subscribe_to_two_ids_at_once() { ); } -/// [req:cap.test.mult] +/// [req:cap.test.mult](https://github.com/mhatzl/evident/wiki/5-REQ-cap#captestmult-multiple-captured-events-received-by-a-subscriber) #[test] fn receiver_for_all_events_two_events_set() { let id_1 = MinId { id: 1 }; diff --git a/tests/pub_sub/threading.rs b/tests/pub_sub/threading.rs index ad0ca77..31b74c6 100644 --- a/tests/pub_sub/threading.rs +++ b/tests/pub_sub/threading.rs @@ -164,7 +164,7 @@ fn set_events_in_many_threads() { } } -/// [req:pub.threaded.test] +/// [req:pub.threaded.test](https://github.com/mhatzl/evident/wiki/5-REQ-pub.threaded#pubthreadedtest-events-set-in-multiple-threads-received-by-subscriber) #[test] fn set_events_in_many_threads_for_one_subscriber() { // Note: This value should be at least 2x lower than the channel bounds set for the publisher. diff --git a/tests/public_concretise/entry.rs b/tests/public_concretise/entry.rs index 135ecf2..b40f171 100644 --- a/tests/public_concretise/entry.rs +++ b/tests/public_concretise/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/public_concretise/id.rs b/tests/public_concretise/id.rs index b2c777a..aa1274e 100644 --- a/tests/public_concretise/id.rs +++ b/tests/public_concretise/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/public_concretise/interim_event.rs b/tests/public_concretise/interim_event.rs index 0186ef1..6295ac2 100644 --- a/tests/public_concretise/interim_event.rs +++ b/tests/public_concretise/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/public_concretise/mod.rs b/tests/public_concretise/mod.rs index bf60d47..dba10e7 100644 --- a/tests/public_concretise/mod.rs +++ b/tests/public_concretise/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and public publisher. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use crate::public_concretise::public_publisher::PUB_PUBLISHER; diff --git a/tests/public_concretise/public_publisher.rs b/tests/public_concretise/public_publisher.rs index a44827d..e5908d1 100644 --- a/tests/public_concretise/public_publisher.rs +++ b/tests/public_concretise/public_publisher.rs @@ -1,7 +1,7 @@ //! This module creates a public [`EvidentPublisher`](evident::publisher::EvidentPublisher), //! and the `set_event!()` macros for this publisher. //! -//! [req:qa.ux.usage] +//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) use evident::publisher::{CaptureMode, EventTimestampKind}; From 1c656372f6228352e442798fd2e43a7f100acd6c Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Fri, 1 Sep 2023 08:49:23 +0200 Subject: [PATCH 31/37] fix: update wiki-link for [req:cap.ctrl] --- src/publisher.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/publisher.rs b/src/publisher.rs index b7acc8a..9639897 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -16,7 +16,7 @@ use crate::{ /// Trait to implement for [`Id`], to control the publisher and all listeners. /// -/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl) +/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl#capctrl-control-capturing) pub trait CaptureControl { /// Returns `true` if the given [`Id`] is used to signal the start of event capturing. /// @@ -183,7 +183,7 @@ where any_event: Arc::new(RwLock::new(HashMap::new())), capturer: send, filter, - // [req:cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.init) + // [req:cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.init#capctrlinit-initial-capturing-state) capturing: Arc::new(AtomicBool::new(true)), capture_blocking: mode, capture_channel_bound, From d12020704ce94580a2d7764de9d0db36526166dd Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Fri, 1 Sep 2023 11:30:21 +0200 Subject: [PATCH 32/37] fix: remove auto-lock-pr action --- .github/workflows/auto-lock-prs.yml | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 .github/workflows/auto-lock-prs.yml diff --git a/.github/workflows/auto-lock-prs.yml b/.github/workflows/auto-lock-prs.yml deleted file mode 100644 index c0ab7ac..0000000 --- a/.github/workflows/auto-lock-prs.yml +++ /dev/null @@ -1,22 +0,0 @@ -# Action to automatically lock PRs after they are merged or closed. -name: "auto-lock PRs" -on: - pull_request_target: - types: [closed] - -jobs: - lock-closed-PRs: - runs-on: ubuntu-latest - permissions: - issues: write - pull-requests: write - steps: - - uses: actions/github-script@v6 - with: - script: | - github.rest.issues.lock({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - lock_reason: "resolved" - }) From 95414dc3942c19875f8524f66e7d698af3f62eaa Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Fri, 1 Sep 2023 11:30:30 +0200 Subject: [PATCH 33/37] fix: remove clutter from templates --- .github/ISSUE_TEMPLATE/add-test.md | 21 +++++------------- .github/ISSUE_TEMPLATE/bug-report-form.yml | 6 ++--- .github/ISSUE_TEMPLATE/bug-report.md | 22 +++++++------------ .github/ISSUE_TEMPLATE/feature-request.md | 16 ++++++-------- .../ISSUE_TEMPLATE/improve-documentation.md | 8 +++---- .github/ISSUE_TEMPLATE/other-topic.md | 4 +--- .github/ISSUE_TEMPLATE/spelling-mistake.md | 8 +++---- .github/ISSUE_TEMPLATE/warn-us.md | 10 ++++----- 8 files changed, 37 insertions(+), 58 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/add-test.md b/.github/ISSUE_TEMPLATE/add-test.md index b4014e0..b9a2f95 100644 --- a/.github/ISSUE_TEMPLATE/add-test.md +++ b/.github/ISSUE_TEMPLATE/add-test.md @@ -2,35 +2,24 @@ name: Add Test about: Propose a new test case. title: "[TEST] " -labels: '' +labels: ["waiting-on-assignee"] assignees: '' --- # Describe your new test case -## Is this test case related to a problem or requirement? +## Is this test case related to other issues/PRs? -Describe your problem or requirement in a clear and concise way. -e.g. I'm always frustrated when […] -## Describe the test case -### Describe the precondition of the test case -Add a clear and concise description of the state the program must be in before executing the test case. +## Describe the test case steps -### Describe the test case steps -Add a clear and concise description of the test case steps. -### Describe the postcondition of the test case +# Describe alternatives you've considered -Add a clear and concise description of the state the program must be in after executing the test case. -## Describe alternatives you've considered - -Add a clear and concise description of any alternative pre-/postconditions or test steps you've considered. # Additional context -Add any other context or screenshots about your proposed test case here. -e.g. Often, […] fails, because […] + diff --git a/.github/ISSUE_TEMPLATE/bug-report-form.yml b/.github/ISSUE_TEMPLATE/bug-report-form.yml index ff6af1f..16cc63e 100644 --- a/.github/ISSUE_TEMPLATE/bug-report-form.yml +++ b/.github/ISSUE_TEMPLATE/bug-report-form.yml @@ -11,7 +11,7 @@ body: id: contact attributes: label: Contact Details - description: How can we get in touch with you if we need more info? + description: How can we get in touch with you if we need more information? placeholder: ex. email@example.com - type: textarea id: what-happened @@ -23,7 +23,7 @@ body: id: version attributes: label: Version - description: What version of evident where you running? + description: What version of our software where you running? placeholder: ex. v1.0.1 or post the git commit hash - type: textarea id: logs @@ -35,7 +35,7 @@ body: id: terms attributes: label: Code of Conduct - description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/mhatzl/evident/blob/main/CODE_OF_CONDUCT.md). + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/mhatzl/project-repo-template/blob/main/CODE_OF_CONDUCT.md). options: - label: I agree to follow this project's Code of Conduct required: true diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index ffcf26e..309c6e6 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -2,36 +2,30 @@ name: Bug Report about: Create a bug report to help us improve. title: "[BUG] " -labels: '' +labels: ["waiting-on-assignee"] assignees: '' --- -# Describe the bug you've found +# Describe the bug you've found, and why you think it is a bug -Add a clear and concise description of what the bug is. -# To Reproduce -Steps to reproduce the behavior: +# To Reproduce -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error '....' +**Steps to reproduce the behavior:** -# Expected behavior +1. ... -Add a clear and concise description of what you expected to happen. # Screenshots -If applicable, add screenshots to help explain your problem. + # Version/Branch used -If applicable, what version/branch was used? + # Additional context -Add any other context about the problem here. + diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index e04b51b..985b894 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -2,26 +2,24 @@ name: Feature Request about: Tell us about a feature you need. title: "[REQ] " -labels: '' +labels: ["waiting-on-assignee", "req-missing-wiki-entry"] assignees: '' --- # Describe your feature request -## Is your feature request related to a problem or requirement? +## Is your feature request related to other issues/PRs? + -Describe your problem or requirement in a clear and concise way. -e.g. I'm always frustrated when […] ## Describe the solution you'd like -Add a clear and concise description of what you want to happen. -## Describe alternatives you've considered -Add a clear and concise description of any alternative solutions or features you've considered. +# Describe alternatives you've considered + + # Additional context -Add any other context or screenshots about your feature request here. -e.g. I often want to do […], because […] + diff --git a/.github/ISSUE_TEMPLATE/improve-documentation.md b/.github/ISSUE_TEMPLATE/improve-documentation.md index c8fe6c4..a49e090 100644 --- a/.github/ISSUE_TEMPLATE/improve-documentation.md +++ b/.github/ISSUE_TEMPLATE/improve-documentation.md @@ -2,7 +2,7 @@ name: Improve Documentation about: Is there something you do not understand? title: "[DOC] " -labels: '' +labels: ["waiting-on-assignee"] assignees: '' --- @@ -10,8 +10,8 @@ assignees: '' # Describe your problem with the current documentation ## Describe what is/was unclear to you -Add a clear and concise description about why the documentation is/was unclear to you. -## Describe what would help you do better understand the problem -Add a clear and concise description about what would help you to better understand the problem. +## Describe what would help you to better understand the documentation + + diff --git a/.github/ISSUE_TEMPLATE/other-topic.md b/.github/ISSUE_TEMPLATE/other-topic.md index b4981a3..5e4cc28 100644 --- a/.github/ISSUE_TEMPLATE/other-topic.md +++ b/.github/ISSUE_TEMPLATE/other-topic.md @@ -2,11 +2,9 @@ name: Other Topic about: Select if you are not sure what else to choose. title: "[OTHER] " -labels: '' +labels: ["waiting-on-assignee"] assignees: '' --- -# Describe your problem -Add a clear and concise description about your problem. diff --git a/.github/ISSUE_TEMPLATE/spelling-mistake.md b/.github/ISSUE_TEMPLATE/spelling-mistake.md index 86eba38..e4b7db5 100644 --- a/.github/ISSUE_TEMPLATE/spelling-mistake.md +++ b/.github/ISSUE_TEMPLATE/spelling-mistake.md @@ -2,16 +2,16 @@ name: Spelling Mistake about: Help us improve our spelling. title: "[SPELL] " -labels: '' +labels: ["waiting-on-assignee", "good-first-issue"] assignees: '' --- # Describe the spelling mistake -## Describe the location(s) of the spelling mistake +## Where is the spelling mistake located? + -Link to or add a screenshot of the location of the spelling mistake. ## Describe the mistake -Add a clear and concise description about what the correct way would be and why? + diff --git a/.github/ISSUE_TEMPLATE/warn-us.md b/.github/ISSUE_TEMPLATE/warn-us.md index 3d49ea4..3d4c184 100644 --- a/.github/ISSUE_TEMPLATE/warn-us.md +++ b/.github/ISSUE_TEMPLATE/warn-us.md @@ -2,16 +2,16 @@ name: Warn Us about: Warn us about a possible problem. title: "[WARN] " -labels: '' +labels: ["waiting-on-assignee"] assignees: '' --- # Describe your warning -## Describe the problem you want to warn us about +## Describe what you want to warn us about -Add a clear and concise description about the problem you want to warn us about. -## Describe what you suggest to do -Add a clear and concise description about your suggested solution to prevent the problem. +## Describe what you suggest doing about it + + From e93dba7b49b21c7f1a568eaa2fd1e61a4b2fe570 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 13 Sep 2023 15:37:45 +0200 Subject: [PATCH 34/37] fix: remove clutter from issue templates --- .github/ISSUE_TEMPLATE/add-test.md | 5 ++--- .github/ISSUE_TEMPLATE/bug-report-form.yml | 2 +- .github/ISSUE_TEMPLATE/bug-report.md | 10 +++++----- .github/ISSUE_TEMPLATE/feature-request.md | 5 ++--- .github/ISSUE_TEMPLATE/improve-documentation.md | 1 - .github/ISSUE_TEMPLATE/spelling-mistake.md | 1 - .github/ISSUE_TEMPLATE/warn-us.md | 1 - .github/pull_request_template.md | 6 +++--- 8 files changed, 13 insertions(+), 18 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/add-test.md b/.github/ISSUE_TEMPLATE/add-test.md index b9a2f95..0aad16b 100644 --- a/.github/ISSUE_TEMPLATE/add-test.md +++ b/.github/ISSUE_TEMPLATE/add-test.md @@ -7,7 +7,6 @@ assignees: '' --- -# Describe your new test case ## Is this test case related to other issues/PRs? @@ -16,10 +15,10 @@ assignees: '' -# Describe alternatives you've considered +## Describe alternatives you've considered -# Additional context +## Additional context diff --git a/.github/ISSUE_TEMPLATE/bug-report-form.yml b/.github/ISSUE_TEMPLATE/bug-report-form.yml index 16cc63e..8ecb42a 100644 --- a/.github/ISSUE_TEMPLATE/bug-report-form.yml +++ b/.github/ISSUE_TEMPLATE/bug-report-form.yml @@ -35,7 +35,7 @@ body: id: terms attributes: label: Code of Conduct - description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/mhatzl/project-repo-template/blob/main/CODE_OF_CONDUCT.md). + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/mhatzl/evident/blob/main/CODE_OF_CONDUCT.md). options: - label: I agree to follow this project's Code of Conduct required: true diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 309c6e6..b9c7a28 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -7,25 +7,25 @@ assignees: '' --- -# Describe the bug you've found, and why you think it is a bug +## Describe the bug you've found, and why you think it is a bug -# To Reproduce +## To Reproduce **Steps to reproduce the behavior:** 1. ... -# Screenshots +## Screenshots -# Version/Branch used +## Version/Branch used -# Additional context +## Additional context diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index 985b894..59d9ad0 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -7,7 +7,6 @@ assignees: '' --- -# Describe your feature request ## Is your feature request related to other issues/PRs? @@ -16,10 +15,10 @@ assignees: '' -# Describe alternatives you've considered +## Describe alternatives you've considered -# Additional context +## Additional context diff --git a/.github/ISSUE_TEMPLATE/improve-documentation.md b/.github/ISSUE_TEMPLATE/improve-documentation.md index a49e090..c55e14e 100644 --- a/.github/ISSUE_TEMPLATE/improve-documentation.md +++ b/.github/ISSUE_TEMPLATE/improve-documentation.md @@ -7,7 +7,6 @@ assignees: '' --- -# Describe your problem with the current documentation ## Describe what is/was unclear to you diff --git a/.github/ISSUE_TEMPLATE/spelling-mistake.md b/.github/ISSUE_TEMPLATE/spelling-mistake.md index e4b7db5..02a78d4 100644 --- a/.github/ISSUE_TEMPLATE/spelling-mistake.md +++ b/.github/ISSUE_TEMPLATE/spelling-mistake.md @@ -7,7 +7,6 @@ assignees: '' --- -# Describe the spelling mistake ## Where is the spelling mistake located? diff --git a/.github/ISSUE_TEMPLATE/warn-us.md b/.github/ISSUE_TEMPLATE/warn-us.md index 3d4c184..fdc82a8 100644 --- a/.github/ISSUE_TEMPLATE/warn-us.md +++ b/.github/ISSUE_TEMPLATE/warn-us.md @@ -7,7 +7,6 @@ assignees: '' --- -# Describe your warning ## Describe what you want to warn us about diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3b450a7..3a0bf72 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,4 @@ -# List of issues that this PR closes +## List of issues that this PR closes [[ @@ -6,7 +6,7 @@ e.g. closes #1 closes #2 … ]] -# Definition of Done ([req:qa.DoD](https://github.com/mhatzl/evident/wiki/5-REQ-qa.DoD#qadod-have-a-definition-of-done-for-requirements)) +## Definition of Done ([req:qa.DoD](https://github.com/mhatzl/evident/wiki/5-REQ-qa.DoD#qadod-have-a-definition-of-done-for-requirements)) **Please consider the following requirements:** @@ -17,7 +17,7 @@ e.g. closes #1 closes #2 … **Note:** You may ignore requirements that are not relevant to your PR. -# Decisions you made for this PR +## Decisions you made for this PR {{ From 525af8178212b37a58374d1bf0b2057d296f0eac Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 13 Sep 2023 15:39:29 +0200 Subject: [PATCH 35/37] fix: apply clippy suggestions --- tests/pub_sub/threading.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/pub_sub/threading.rs b/tests/pub_sub/threading.rs index 31b74c6..5ec23ec 100644 --- a/tests/pub_sub/threading.rs +++ b/tests/pub_sub/threading.rs @@ -203,7 +203,7 @@ fn set_events_in_many_threads_for_one_subscriber() { .recv_timeout(std::time::Duration::from_millis(10)) .unwrap(); - recv_ids.push(event.get_event_id().clone()); + recv_ids.push(*event.get_event_id()); } for i in 1..=THREAD_CNT { From 41f51928edcea5608e8c54f5e8e9fe01ef0eb5d2 Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 13 Sep 2023 15:45:11 +0200 Subject: [PATCH 36/37] fix: remove wiki-links from references --- .github/pull_request_template.md | 10 ++-- .github/workflows/rust.yml | 14 ++--- src/creation_macros.rs | 8 +-- src/event/entry.rs | 16 +++--- src/event/mod.rs | 24 ++++----- src/event/origin.rs | 6 +-- src/publisher.rs | 60 ++++++++++----------- src/subscription.rs | 8 +-- tests/min_concretise/entry.rs | 2 +- tests/min_concretise/id.rs | 6 +-- tests/min_concretise/interim_event.rs | 2 +- tests/min_concretise/mod.rs | 4 +- tests/min_filter/entry.rs | 2 +- tests/min_filter/filter.rs | 2 +- tests/min_filter/id.rs | 2 +- tests/min_filter/interim_event.rs | 2 +- tests/min_filter/mod.rs | 2 +- tests/min_msg/entry.rs | 2 +- tests/min_msg/id.rs | 2 +- tests/min_msg/interim_event.rs | 2 +- tests/min_msg/mod.rs | 2 +- tests/min_msg/msg.rs | 2 +- tests/pub_sub/set_events.rs | 8 +-- tests/pub_sub/subscription.rs | 2 +- tests/pub_sub/threading.rs | 2 +- tests/public_concretise/entry.rs | 2 +- tests/public_concretise/id.rs | 2 +- tests/public_concretise/interim_event.rs | 2 +- tests/public_concretise/mod.rs | 2 +- tests/public_concretise/public_publisher.rs | 2 +- 30 files changed, 101 insertions(+), 101 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3a0bf72..89a0e57 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,14 +6,14 @@ e.g. closes #1 closes #2 … ]] -## Definition of Done ([req:qa.DoD](https://github.com/mhatzl/evident/wiki/5-REQ-qa.DoD#qadod-have-a-definition-of-done-for-requirements)) +## Definition of Done ([req:qa.DoD]) **Please consider the following requirements:** -- [ ] Add/Update requirement references (see: [req:qa.tracing](https://github.com/mhatzl/evident/wiki/5-REQ-qa.tracing#qatracing-use-requirement-ids-in-the-evident-repository)) -- [ ] Add usage examples in doc-comments (see: [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples)) -- [ ] Only use macros if they improve *evident's* usability (see: [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability)) -- [ ] Prefer `RwLock` over `Mutex` (see: [req:qa.perf.locks](https://github.com/mhatzl/evident/wiki/5-REQ-qa.perf.locks#qaperflocks-performance-impact-of-multithreaded-locking)) +- [ ] Add/Update requirement references (see: [req:qa.tracing]) +- [ ] Add usage examples in doc-comments (see: [req:qa.ux.usage]) +- [ ] Only use macros if they improve *evident's* usability (see: [req:qa.ux.macros]) +- [ ] Prefer `RwLock` over `Mutex` (see: [req:qa.perf.locks]) **Note:** You may ignore requirements that are not relevant to your PR. diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 6654b2c..a538c25 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -10,7 +10,7 @@ env: CARGO_TERM_COLOR: always jobs: - # [req:qa.pipeline.1_style](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.1_style#qapipeline1_style-ensure-consistent-formatting) + # [req:qa.pipeline.1_style] format: name: Check Formatting runs-on: ubuntu-latest @@ -20,11 +20,11 @@ jobs: - name: Run cargo fmt run: cargo fmt -- --check - # [req:qa.pipeline.2_lint](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.2_lint#qapipeline2_lint-ensure-good-coding-standard) + # [req:qa.pipeline.2_lint] lint: name: Run Linter (clippy) runs-on: ubuntu-latest - # [req:qa.sustain](https://github.com/mhatzl/evident/wiki/5-REQ-qa.sustain#qasustain-consider-sustainability-during-design-and-development) + # [req:qa.sustain] needs: format steps: @@ -32,11 +32,11 @@ jobs: - name: Run linter run: cargo clippy -- -D warnings - # [req:qa.pipeline.3_build](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.3_build#qapipeline3_build-ensure-evident-builds) + # [req:qa.pipeline.3_build] build: name: Run Build runs-on: ubuntu-latest - # [req:qa.sustain](https://github.com/mhatzl/evident/wiki/5-REQ-qa.sustain#qasustain-consider-sustainability-during-design-and-development) + # [req:qa.sustain] needs: lint steps: @@ -44,11 +44,11 @@ jobs: - name: Build run: cargo build --verbose - # [req:qa.pipeline.4_tests](https://github.com/mhatzl/evident/wiki/5-REQ-qa.pipeline.4_tests#qapipeline4_tests-ensure-tests-still-pass) + # [req:qa.pipeline.4_tests] test: name: Run Tests runs-on: ubuntu-latest - # [req:qa.sustain](https://github.com/mhatzl/evident/wiki/5-REQ-qa.sustain#qasustain-consider-sustainability-during-design-and-development) + # [req:qa.sustain] needs: build steps: diff --git a/src/creation_macros.rs b/src/creation_macros.rs index 8f628bd..68fc42b 100644 --- a/src/creation_macros.rs +++ b/src/creation_macros.rs @@ -57,7 +57,7 @@ /// ); /// ``` /// -/// [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) +/// [req:qa.ux.macros] #[macro_export] macro_rules! create_static_publisher { ($publisher_name:ident, @@ -285,7 +285,7 @@ macro_rules! z__create_static_publisher { /// ); /// ``` /// -/// [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) +/// [req:qa.ux.macros] #[macro_export] macro_rules! create_set_event_macro { (id_type = $id_t:ty, @@ -315,7 +315,7 @@ macro_rules! create_set_event_macro { /// set_event!(id, msg).finalize(); /// ``` /// - /// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) + /// [req:event.set], [req:qa.ux.macros] #[macro_export] macro_rules! set_event { ($id:expr) => { @@ -361,7 +361,7 @@ macro_rules! create_set_event_macro { /// set_event!(id, msg).finalize(); /// ``` /// - /// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) + /// [req:event.set], [req:qa.ux.macros] macro_rules! set_event { ($id:expr) => { $crate::event::set_event::<$id_t, $msg_t, $entry_t, $interm_event_t>( diff --git a/src/event/entry.rs b/src/event/entry.rs index b0989e5..3da55ca 100644 --- a/src/event/entry.rs +++ b/src/event/entry.rs @@ -1,6 +1,6 @@ //! Contains the [`EventEntry] trait. //! -//! [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry) +//! [req:event.entry] use std::hash::Hash; @@ -14,7 +14,7 @@ use super::{origin::Origin, Id, Msg}; /// /// **Note:** Since it is a trait, the custom implementation may contain additional fields and functions. /// -/// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry), [req:event.entry.generic](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry.generic#evententrygeneric-generic-event-entry) +/// [req:event.entry], [req:event.entry.generic] pub trait EventEntry: Default + Clone + Hash + Send + Sync + 'static { /// Creates a new [`EventEntry`]. /// @@ -26,32 +26,32 @@ pub trait EventEntry: Default + Clone + Hash + Send + Sync + 'sta /// * `msg` ... Optional main event message /// * `origin` ... The [`Origin`] the event was set at /// - /// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry), [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier), [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message), [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) + /// [req:event.entry], [req:event.id], [req:event.msg], [req:event.origin] fn new(event_id: K, msg: Option>, origin: Origin) -> Self; /// Returns the [`Id`] of this event. /// - /// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier) + /// [req:event.id] fn get_event_id(&self) -> &K; /// Convert this [`EventEntry`] into the [`Id`] of this event. /// - /// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier) + /// [req:event.id] fn into_event_id(self) -> K; /// Get the entry-ID that was generated when the event was set. /// - /// [req:event.entry.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry.id#evententryid-unique-event-entry) + /// [req:event.entry.id] fn get_entry_id(&self) -> crate::uuid::Uuid; /// Get the main message that was given when the event was set, /// or `None` if no message was given. /// - /// [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) + /// [req:event.msg] fn get_msg(&self) -> Option<&M>; /// Get the [`Origin`] the event was set at. /// - /// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) + /// [req:event.origin] fn get_origin(&self) -> &Origin; } diff --git a/src/event/mod.rs b/src/event/mod.rs index 00fa68f..865c8f7 100644 --- a/src/event/mod.rs +++ b/src/event/mod.rs @@ -1,6 +1,6 @@ //! Contains the *evident* [`Event`], and all related traits, structures, and functions. //! -//! [req:event](https://github.com/mhatzl/evident/wiki/5-REQ-event#event-structure-of-an-evident-event) +//! [req:event] use std::marker::PhantomData; @@ -18,7 +18,7 @@ pub mod origin; /// /// The optional [`Filter`](self::filter::Filter) trait must also use the same implementation of this [`Id`] trait. /// -/// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier), [req:event.id.generic](https://github.com/mhatzl/evident/wiki/5-REQ-event.id.generic#eventidgeneric-generic-event-id) +/// [req:event.id], [req:event.id.generic] pub trait Id: core::fmt::Debug + Default + Clone + std::hash::Hash + PartialEq + Eq + Send + Sync + 'static { @@ -32,7 +32,7 @@ pub trait Id: /// /// **Note:** This trait is already implemented for [`String`]. /// -/// [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) +/// [req:event.msg] pub trait Msg: core::fmt::Debug + Clone + Send + Sync + 'static {} impl Msg for String {} @@ -46,7 +46,7 @@ impl Msg for String {} /// * `msg` ... Main message that is set for this event /// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) /// -/// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) +/// [req:event.set], [req:event.origin] pub fn set_event_with_msg, I: IntermediaryEvent>( event_id: K, msg: impl Into, @@ -63,7 +63,7 @@ pub fn set_event_with_msg, I: IntermediaryEve /// * `event_id` ... The [`Id`] used for this event /// * `origin` ... The [`Origin`] the event was set at (Note: Use macro [`this_origin`](crate::this_origin)) /// -/// [req:event.set](https://github.com/mhatzl/evident/wiki/5-REQ-event.set#eventset-set-an-event), [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) +/// [req:event.set], [req:event.origin] pub fn set_event, I: IntermediaryEvent>( event_id: K, origin: Origin, @@ -74,7 +74,7 @@ pub fn set_event, I: IntermediaryEvent where @@ -84,7 +84,7 @@ where { /// [`EventEntry`] of the event. /// - /// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry) + /// [req:event.entry] pub(crate) entry: T, // PahmtomData needed for unused generics @@ -120,21 +120,21 @@ impl> Event { /// Returns the [`Id`] of this event. /// - /// [req:event.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.id#eventid-event-identifier) + /// [req:event.id] pub fn get_event_id(&self) -> &K { self.entry.get_event_id() } /// Returns the [`EventEntry`] of this event. /// - /// [req:event.entry](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry#evententry-event-entry) + /// [req:event.entry] pub fn get_entry(&self) -> &T { &self.entry } /// Get the entry-ID that was generated when the event was set. /// - /// [req:event.entry.id](https://github.com/mhatzl/evident/wiki/5-REQ-event.entry.id#evententryid-unique-event-entry) + /// [req:event.entry.id] pub fn get_entry_id(&self) -> crate::uuid::Uuid { self.entry.get_entry_id() } @@ -142,14 +142,14 @@ impl> Event { /// Get the main message that was given when the event was set, /// or `None` if no message was given. /// - /// [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) + /// [req:event.msg] pub fn get_msg(&self) -> Option<&M> { self.entry.get_msg() } /// Get the [`Origin`] the event was set at. /// - /// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) + /// [req:event.origin] pub fn get_origin(&self) -> &Origin { self.entry.get_origin() } diff --git a/src/event/origin.rs b/src/event/origin.rs index 6bfa8f6..8e12bbf 100644 --- a/src/event/origin.rs +++ b/src/event/origin.rs @@ -3,7 +3,7 @@ /// Structure to point to a location in the program code. /// It is used to know where the event was set, but may be used for other use cases aswell. /// -/// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) +/// [req:event.origin] #[derive(Debug, Default, PartialEq, Eq, Clone)] pub struct Origin { /// Module path to the code location. @@ -31,7 +31,7 @@ impl Origin { /// * `filename` ... Filename where the code is located /// * `line_nr` ... Line number where the code is located /// - /// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin) + /// [req:event.origin] pub fn new(module_path: &'static str, filename: &'static str, line_nr: u32) -> Self { Origin { module_path, @@ -59,7 +59,7 @@ impl core::fmt::Display for Origin { /// Convenience wrapper to create an [`Origin`] for the code position this macro is used at. /// -/// [req:event.origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigin-get-the-event-origin), [req:qa.ux.macros](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.macros#qauxmacros-use-macros-if-it-improves-usability) +/// [req:event.origin], [req:qa.ux.macros] #[macro_export] macro_rules! this_origin { () => { diff --git a/src/publisher.rs b/src/publisher.rs index 9639897..18a3713 100644 --- a/src/publisher.rs +++ b/src/publisher.rs @@ -16,7 +16,7 @@ use crate::{ /// Trait to implement for [`Id`], to control the publisher and all listeners. /// -/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl#capctrl-control-capturing) +/// [req:cap.ctrl] pub trait CaptureControl { /// Returns `true` if the given [`Id`] is used to signal the start of event capturing. /// @@ -26,12 +26,12 @@ pub trait CaptureControl { /// id == &START_CAPTURING_ID /// ``` /// - /// [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) + /// [req:cap.ctrl.start] fn start(id: &Self) -> bool; /// Returns the *start-ID*. /// - /// [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) + /// [req:cap.ctrl.start] fn start_id() -> Self; /// Returns `true` if the given [`Id`] is used to signal the end of event capturing. @@ -42,18 +42,18 @@ pub trait CaptureControl { /// id == &STOP_CAPTURING_ID /// ``` /// - /// [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) + /// [req:cap.ctrl.stop] fn stop(id: &Self) -> bool; /// Returns the *stop-ID*. /// - /// [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) + /// [req:cap.ctrl.stop] fn stop_id() -> Self; } /// Returns `true` if the given [`Id`] is used to control capturing. /// -/// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl#capctrl-control-capturing) +/// [req:cap.ctrl] pub fn is_control_id(id: &impl CaptureControl) -> bool { CaptureControl::stop(id) || CaptureControl::start(id) } @@ -86,7 +86,7 @@ type Capturer = SyncSender>; /// An **EvidentPublisher** is used to capture, publish, and manage subscriptions. /// -/// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing) +/// [req:pub] pub struct EvidentPublisher where K: Id + CaptureControl, @@ -96,27 +96,27 @@ where { /// The hashmap of subscribers listening to specific events. /// - /// [req:subs.specific](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific#subsspecific-subscribe-to-specific-events) + /// [req:subs.specific] pub(crate) subscriptions: Arc>>, /// The hashmap of subscribers listening to all events. /// - /// [req:subs.all](https://github.com/mhatzl/evident/wiki/5-REQ-subs.all#subsall-subscribe-to-all-events) + /// [req:subs.all] pub(crate) any_event: Arc>>, /// The send-part of the capturing channel. /// - /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) + /// [req:cap] pub(crate) capturer: Capturer, /// Optional filter that is applied when capturing events. /// - /// [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) + /// [req:cap.filter] filter: Option, /// Flag to control if capturing is active or inactive. /// - /// [req:cap.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl#capctrl-control-capturing) + /// [req:cap.ctrl] capturing: Arc, /// Flag to control the capture mode. @@ -124,12 +124,12 @@ where /// Defines the size of the capturing send-buffer. /// - /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) + /// [req:cap] capture_channel_bound: usize, /// Defines the size of each subscription send-buffer. /// - /// [req:subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#subs-subscribing-to-events) + /// [req:subs] subscription_channel_bound: usize, /// Number of missed captures in *non-blocking* capture mode. @@ -150,7 +150,7 @@ where /// /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. /// - /// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing) + /// [req:pub] fn create( mut on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: Option, @@ -162,7 +162,7 @@ where let (send, recv): (SyncSender>, _) = mpsc::sync_channel(capture_channel_bound); - // [req:pub.threaded](https://github.com/mhatzl/evident/wiki/5-REQ-pub.threaded#pubthreaded-multithreaded-publishing) + // [req:pub.threaded] thread::spawn(move || { while let Ok(mut event) = recv.recv() { if timestamp_kind == EventTimestampKind::Captured { @@ -183,7 +183,7 @@ where any_event: Arc::new(RwLock::new(HashMap::new())), capturer: send, filter, - // [req:cap.ctrl.init](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.init#capctrlinit-initial-capturing-state) + // [req:cap.ctrl.init] capturing: Arc::new(AtomicBool::new(true)), capture_blocking: mode, capture_channel_bound, @@ -197,7 +197,7 @@ where /// /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. /// - /// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing) + /// [req:pub] pub fn new( on_event: impl FnMut(Event) + std::marker::Send + 'static, capture_mode: CaptureMode, @@ -219,7 +219,7 @@ where /// /// **Note:** You should use the macro [`create_static_publisher`](crate::create_static_publisher) instead. /// - /// [req:pub](https://github.com/mhatzl/evident/wiki/5-REQ-pub#pub-event-publishing), [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) + /// [req:pub], [req:cap.filter] pub fn with( on_event: impl FnMut(Event) + std::marker::Send + 'static, filter: F, @@ -240,14 +240,14 @@ where /// Returns the event filter, or `None` if no filter is set. /// - /// [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) + /// [req:cap.filter] pub fn get_filter(&self) -> &Option { &self.filter } /// Returns `true` if the given event-entry passes the filter, or the event-ID is a control-ID. /// - /// [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) + /// [req:cap.filter] pub fn entry_allowed(&self, entry: &impl EventEntry) -> bool { if !is_control_id(entry.get_event_id()) { if !self.capturing.load(Ordering::Acquire) { @@ -268,12 +268,12 @@ where /// /// **Note:** This function should **not** be called manually, because it is automatically called on `drop()` of an intermediary event. /// - /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) + /// [req:cap] #[doc(hidden)] pub fn _capture>(&self, interm_event: &mut I) { let entry = interm_event.take_entry(); - // [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) + // [req:cap.filter] if !self.entry_allowed(&entry) { return; } @@ -332,7 +332,7 @@ where /// Returns a subscription to events with the given event-ID, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [req:subs.specific.one](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.one#subsspecificone-subscribe-to-one-specific-event) + /// [req:subs.specific.one] pub fn subscribe(&self, id: K) -> Result, SubscriptionError> { self.subscribe_to_many(vec![id]) } @@ -340,7 +340,7 @@ where /// Returns a subscription to events with the given event-IDs, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [req:subs.specific.mult](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.mult#subsspecificmult-subscribe-to-multiple-specific-events) + /// [req:subs.specific.mult] pub fn subscribe_to_many( &self, ids: Vec, @@ -383,7 +383,7 @@ where /// Returns a subscription to all events, /// or a [`SubscriptionError`] if the subscription could not be created. /// - /// [req:subs.all](https://github.com/mhatzl/evident/wiki/5-REQ-subs.all#subsall-subscribe-to-all-events) + /// [req:subs.all] pub fn subscribe_to_all_events( &self, ) -> Result, SubscriptionError> { @@ -410,7 +410,7 @@ where /// Returns `true` if capturing is *active*. /// - /// [req:cap.ctrl.info](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.info#capctrlinfo-get-capturing-state) + /// [req:cap.ctrl.info] pub fn is_capturing(&self) -> bool { self.capturing.load(Ordering::Acquire) } @@ -419,7 +419,7 @@ where /// /// **Note:** Capturing is already started initially, so this function is only needed after manually stopping capturing. /// - /// [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) + /// [req:cap.ctrl.start] pub fn start(&self) { let empty_msg: Option = None; let start_event = Event::new(EventEntry::new(K::start_id(), empty_msg, this_origin!())); @@ -431,7 +431,7 @@ where /// Stop capturing. /// - /// [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) + /// [req:cap.ctrl.stop] pub fn stop(&self) { let empty_msg: Option = None; let stop_event = Event::new(EventEntry::new(K::stop_id(), empty_msg, this_origin!())); @@ -445,7 +445,7 @@ where /// /// **Note:** This function should **not** be called manually, because it is already called in the event handler. /// - /// [req:cap](https://github.com/mhatzl/evident/wiki/5-REQ-cap#cap-capturing-events) + /// [req:cap] #[doc(hidden)] pub fn on_event(&self, event: Event) { let arc_event = Arc::new(event); diff --git a/src/subscription.rs b/src/subscription.rs index d38eb06..22d1333 100644 --- a/src/subscription.rs +++ b/src/subscription.rs @@ -14,7 +14,7 @@ use crate::{ /// Subscription that is returned when subscribing to events captured by an [`EvidentPublisher`]. /// -///[req:subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#subs-subscribing-to-events) +///[req:subs] pub struct Subscription<'p, K, M, T, F> where K: Id + CaptureControl, @@ -134,7 +134,7 @@ where /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events /// - /// [req:subs.specific.one](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.one#subsspecificone-subscribe-to-one-specific-event) + /// [req:subs.specific.one] pub fn subscribe_id(&mut self, id: K) -> Result<(), SubscriptionError> { self.subscribe_many(vec![id]) } @@ -154,7 +154,7 @@ where /// * [`SubscriptionError::NoSubscriptionChannelAvailable`] ... If the [`EvidentPublisher`] has no stored channel to this [`Subscription`] /// * [`SubscriptionError::AllEventsSubscriptionNotModifiable`] ... If the [`Subscription`] was created to receive all events /// - /// [req:subs.specific.mult](https://github.com/mhatzl/evident/wiki/5-REQ-subs.specific.mult#subsspecificmult-subscribe-to-multiple-specific-events) + /// [req:subs.specific.mult] pub fn subscribe_many(&mut self, ids: Vec) -> Result<(), SubscriptionError> { if self.sub_to_all || self.subscriptions.is_none() { return Err(SubscriptionError::AllEventsSubscriptionNotModifiable); @@ -305,7 +305,7 @@ pub enum SubscriptionError { /// *Sender-part* of the subscription-channel between a [`Subscription`] and an [`EvidentPublisher`]. /// -/// [req:subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#subs-subscribing-to-events) +/// [req:subs] #[derive(Clone)] pub(crate) struct SubscriptionSender where diff --git a/tests/min_concretise/entry.rs b/tests/min_concretise/entry.rs index dca389f..2c15175 100644 --- a/tests/min_concretise/entry.rs +++ b/tests/min_concretise/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_concretise/id.rs b/tests/min_concretise/id.rs index 62462ba..09a8011 100644 --- a/tests/min_concretise/id.rs +++ b/tests/min_concretise/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] /// Struct used for a minimal [`Id`](evident::event::Id) trait implementation. #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] @@ -12,12 +12,12 @@ impl evident::event::Id for MinId {} /// Event-ID to notify the publisher and all listeners that capturing should be started. /// -/// [req:event.id.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-event.id.ctrl#eventidctrl-event-ids-for-capture-control), [req:cap.ctrl.start](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.start#capctrlstart-start-capturing) +/// [req:event.id.ctrl], [req:cap.ctrl.start] const START_CAPTURING: MinId = MinId { id: -1 }; /// Event-ID to notify the publisher and all listeners that capturing should be stopped. /// -/// [req:event.id.ctrl](https://github.com/mhatzl/evident/wiki/5-REQ-event.id.ctrl#eventidctrl-event-ids-for-capture-control), [req:cap.ctrl.stop](https://github.com/mhatzl/evident/wiki/5-REQ-cap.ctrl.stop#capctrlstop-stop-capturing) +/// [req:event.id.ctrl], [req:cap.ctrl.stop] const STOP_CAPTURING: MinId = MinId { id: -2 }; impl evident::publisher::CaptureControl for MinId { diff --git a/tests/min_concretise/interim_event.rs b/tests/min_concretise/interim_event.rs index ace694c..6b5ac12 100644 --- a/tests/min_concretise/interim_event.rs +++ b/tests/min_concretise/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_concretise/mod.rs b/tests/min_concretise/mod.rs index b6da364..b7e9dcf 100644 --- a/tests/min_concretise/mod.rs +++ b/tests/min_concretise/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident*. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; @@ -34,7 +34,7 @@ evident::create_set_event_macro!( /// Test using the minimal pub/sub implementation to set and listen to an event. /// -/// [req:cap.test.recv](https://github.com/mhatzl/evident/wiki/5-REQ-cap#captestrecv-captured-event-received-by-a-subscriber) +/// [req:cap.test.recv] #[test] fn setup_minimal_publisher() { let some_id = MinId { id: 3 }; diff --git a/tests/min_filter/entry.rs b/tests/min_filter/entry.rs index b40f171..135ecf2 100644 --- a/tests/min_filter/entry.rs +++ b/tests/min_filter/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_filter/filter.rs b/tests/min_filter/filter.rs index 2907356..32823e4 100644 --- a/tests/min_filter/filter.rs +++ b/tests/min_filter/filter.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Filter`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples), [req:cap.filter](https://github.com/mhatzl/evident/wiki/5-REQ-cap.filter#capfilter-filter-captured-events) +//! [req:qa.ux.usage], [req:cap.filter] use evident::event::filter::Filter; diff --git a/tests/min_filter/id.rs b/tests/min_filter/id.rs index cd718f5..06261fe 100644 --- a/tests/min_filter/id.rs +++ b/tests/min_filter/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/min_filter/interim_event.rs b/tests/min_filter/interim_event.rs index 6295ac2..0186ef1 100644 --- a/tests/min_filter/interim_event.rs +++ b/tests/min_filter/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_filter/mod.rs b/tests/min_filter/mod.rs index e2faa31..34998e5 100644 --- a/tests/min_filter/mod.rs +++ b/tests/min_filter/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and [`Filter`](evident::event::filter::Filter). //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; diff --git a/tests/min_msg/entry.rs b/tests/min_msg/entry.rs index 6e07ae2..430f74c 100644 --- a/tests/min_msg/entry.rs +++ b/tests/min_msg/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/min_msg/id.rs b/tests/min_msg/id.rs index aa1274e..b2c777a 100644 --- a/tests/min_msg/id.rs +++ b/tests/min_msg/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/min_msg/interim_event.rs b/tests/min_msg/interim_event.rs index 733c050..8f5b33b 100644 --- a/tests/min_msg/interim_event.rs +++ b/tests/min_msg/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/min_msg/mod.rs b/tests/min_msg/mod.rs index 83cc91f..411d540 100644 --- a/tests/min_msg/mod.rs +++ b/tests/min_msg/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and a custom [`Msg`](evident::event::Msg). //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; diff --git a/tests/min_msg/msg.rs b/tests/min_msg/msg.rs index c93b6e7..4ecf430 100644 --- a/tests/min_msg/msg.rs +++ b/tests/min_msg/msg.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Msg`](evident::event::Msg) trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples), [req:event.msg](https://github.com/mhatzl/evident/wiki/5-REQ-event.msg#eventmsg-event-message) +//! [req:qa.ux.usage], [req:event.msg] /// Struct used for a minimal [`Msg`](evident::event::Msg) trait implementation. #[derive(Debug, Clone, PartialEq, Eq)] diff --git a/tests/pub_sub/set_events.rs b/tests/pub_sub/set_events.rs index 4ee4da1..6eedc11 100644 --- a/tests/pub_sub/set_events.rs +++ b/tests/pub_sub/set_events.rs @@ -8,7 +8,7 @@ use crate::pub_sub::setup::{ entry::MinEventEntry, id::MinId, interim_event::MinInterimEvent, TESTS_PUBLISHER, }; -/// [req:event.origin.test.basic](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigintestbasic-origin-of-set-event-points-to-set_event-call) +/// [req:event.origin.test.basic] #[test] fn set_event_has_correct_origin() { let id = MinId { id: 1 }; @@ -52,7 +52,7 @@ fn set_event_has_correct_origin() { ); } -/// [req:event.origin.test.two_origins](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigintesttwo_origins-origin-of-an-event-set-with-two-set_event-calls-differs) +/// [req:event.origin.test.two_origins] #[test] fn set_same_event_twice_with_different_origin() { let id = MinId { id: 1 }; @@ -104,7 +104,7 @@ fn set_same_event_twice_with_different_origin() { ); } -/// [req:event.origin.test.same_origin](https://github.com/mhatzl/evident/wiki/5-REQ-event.origin#eventorigintestsame_origin-set-origin-of-an-event-manually-for-two-set_event_with_msg-calls) +/// [req:event.origin.test.same_origin] #[test] fn set_same_event_twice_with_same_origin() { let id = MinId { id: 1 }; @@ -152,7 +152,7 @@ fn set_same_event_twice_with_same_origin() { assert_ne!(event_1, event_2, "Received events are equal."); } -/// [req:subs.test.mult_subs](https://github.com/mhatzl/evident/wiki/5-REQ-subs#substestmult_subs-multiple-subscribers-to-same-event) +/// [req:subs.test.mult_subs] #[test] fn set_event_received_exactly_once_per_receiver() { let id = MinId { id: 1 }; diff --git a/tests/pub_sub/subscription.rs b/tests/pub_sub/subscription.rs index efed867..9d5d282 100644 --- a/tests/pub_sub/subscription.rs +++ b/tests/pub_sub/subscription.rs @@ -131,7 +131,7 @@ fn subscribe_to_two_ids_at_once() { ); } -/// [req:cap.test.mult](https://github.com/mhatzl/evident/wiki/5-REQ-cap#captestmult-multiple-captured-events-received-by-a-subscriber) +/// [req:cap.test.mult] #[test] fn receiver_for_all_events_two_events_set() { let id_1 = MinId { id: 1 }; diff --git a/tests/pub_sub/threading.rs b/tests/pub_sub/threading.rs index 5ec23ec..8d8f60a 100644 --- a/tests/pub_sub/threading.rs +++ b/tests/pub_sub/threading.rs @@ -164,7 +164,7 @@ fn set_events_in_many_threads() { } } -/// [req:pub.threaded.test](https://github.com/mhatzl/evident/wiki/5-REQ-pub.threaded#pubthreadedtest-events-set-in-multiple-threads-received-by-subscriber) +/// [req:pub.threaded.test] #[test] fn set_events_in_many_threads_for_one_subscriber() { // Note: This value should be at least 2x lower than the channel bounds set for the publisher. diff --git a/tests/public_concretise/entry.rs b/tests/public_concretise/entry.rs index b40f171..135ecf2 100644 --- a/tests/public_concretise/entry.rs +++ b/tests/public_concretise/entry.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`EventEntry`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, origin::Origin}; diff --git a/tests/public_concretise/id.rs b/tests/public_concretise/id.rs index aa1274e..b2c777a 100644 --- a/tests/public_concretise/id.rs +++ b/tests/public_concretise/id.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`Id`](evident::event::Id) trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, Copy)] pub struct MinId { diff --git a/tests/public_concretise/interim_event.rs b/tests/public_concretise/interim_event.rs index 6295ac2..0186ef1 100644 --- a/tests/public_concretise/interim_event.rs +++ b/tests/public_concretise/interim_event.rs @@ -1,6 +1,6 @@ //! This module contains the minimal required implementation for the [`IntermediaryEvent`] trait. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::event::{entry::EventEntry, intermediary::IntermediaryEvent, origin::Origin}; diff --git a/tests/public_concretise/mod.rs b/tests/public_concretise/mod.rs index dba10e7..bf60d47 100644 --- a/tests/public_concretise/mod.rs +++ b/tests/public_concretise/mod.rs @@ -1,6 +1,6 @@ //! This module contains minimal required implementations to create a pub/sub-setup with *evident* and public publisher. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use crate::public_concretise::public_publisher::PUB_PUBLISHER; diff --git a/tests/public_concretise/public_publisher.rs b/tests/public_concretise/public_publisher.rs index e5908d1..a44827d 100644 --- a/tests/public_concretise/public_publisher.rs +++ b/tests/public_concretise/public_publisher.rs @@ -1,7 +1,7 @@ //! This module creates a public [`EvidentPublisher`](evident::publisher::EvidentPublisher), //! and the `set_event!()` macros for this publisher. //! -//! [req:qa.ux.usage](https://github.com/mhatzl/evident/wiki/5-REQ-qa.ux.usage#qauxusage-provide-usage-examples) +//! [req:qa.ux.usage] use evident::publisher::{CaptureMode, EventTimestampKind}; From 3a255f8ff377c2c9fc030cde83d893a29d3904ce Mon Sep 17 00:00:00 2001 From: Manuel Hatzl Date: Wed, 13 Sep 2023 16:19:20 +0200 Subject: [PATCH 37/37] feat: add mantra workflows --- .github/workflows/mantra_pr.yml | 55 +++++++++++++++++++++++ .github/workflows/mantra_sync.yml | 63 ++++++++++++++++++++++++++ .github/workflows/release-please.yml | 67 +++++++++++++++++++++++++++- 3 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/mantra_pr.yml create mode 100644 .github/workflows/mantra_sync.yml diff --git a/.github/workflows/mantra_pr.yml b/.github/workflows/mantra_pr.yml new file mode 100644 index 0000000..832ef39 --- /dev/null +++ b/.github/workflows/mantra_pr.yml @@ -0,0 +1,55 @@ +# Runs mantra check to write the overview of reference changes in a PR comment. +name: mantra-pr +on: + pull_request: + +permissions: + issues: write + pull-requests: write + +jobs: + mantra-pr: + runs-on: ubuntu-latest + container: + image: manuelhatzl/mantra:main + + env: + BRANCH_NAME: ${{ github.base_ref }} + + steps: + - uses: actions/checkout@v3 + with: + repository: 'mhatzl/evident-wiki' + path: './req_folder' + sparse-checkout: 5-Requirements + + - uses: actions/checkout@v3 + with: + path: './proj_folder' + + - name: check + id: check + # '&>' to get stderr and stdout in one file, so error logs get included in output. + # Uses ' ' (U+2002) instead of regular space for output, because GitHub output cannot handle regular spaces + # see: https://stackoverflow.com/questions/59191913/how-do-i-get-the-output-of-a-specific-step-in-github-actions + run: | + mantra check --branch-name=$BRANCH_NAME ./req_folder ./proj_folder &> check_overview.md + output="$(cat check_overview.md)" + output="${output//\'/\\\'}" + output="${output//\"/\\\"}" + output="${output//$'\n'/\\\\n}" + output="${output// / }" + cat check_overview.md + echo "check-overview=$output" >> $GITHUB_OUTPUT + + - name: comment + uses: actions/github-script@v6 + with: + script: | + const check_overview = '${{ steps.check.outputs.check-overview }}'.replaceAll('\\n', '\n') + await github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: check_overview + }) diff --git a/.github/workflows/mantra_sync.yml b/.github/workflows/mantra_sync.yml new file mode 100644 index 0000000..84cf8a9 --- /dev/null +++ b/.github/workflows/mantra_sync.yml @@ -0,0 +1,63 @@ +name: mantra-sync +on: + push: + branches: main + +permissions: + contents: write + +jobs: + # Synchronizes references between project and wiki. + mantra-sync: + runs-on: ubuntu-latest + container: + image: manuelhatzl/mantra:main + + env: + BRANCH_NAME: ${{ github.ref_name }} + + steps: + - uses: actions/checkout@v3 + with: + repository: 'mhatzl/evident-wiki' + path: './wiki' + # PAT with 'workflow' permission required in case wiki-links in workflow files get updated + token: ${{ secrets.EVIDENT_TOKEN }} + + - uses: actions/checkout@v3 + with: + path: './proj_folder' + + - name: sync-references + run: mantra sync --branch-name=$BRANCH_NAME --branch-link=https://github.com/mhatzl/evident/tree/$BRANCH_NAME ./wiki/5-Requirements ./proj_folder + + - name: job-date + id: job-date + # '-u' for UTC + run: | + echo "date=$(date -u +'%Y-%m-%d_%H:%M UTC')" >> $GITHUB_OUTPUT + + - name: update-sidebar + run: | + sed -i -r "s/\*\*Last update:\*\*.+/\*\*Last update:\*\* ${{ steps.job-date.outputs.date }} /" ./wiki/_Sidebar.md + repo=$(echo "${{ github.repository }}") + repo=${repo//\//\\/} + sed -i -r "s/\*\*Repository:\*\*.+/\*\*Repository:\*\* $repo /" ./wiki/_Sidebar.md + sed -i -r "s/\*\*Branch:\*\*.+/\*\*Branch:\*\* $BRANCH_NAME /" ./wiki/_Sidebar.md + short_sha=$(echo "${{ github.sha }}") + short_sha=${short_sha:0:7} + commit_link=$(echo "${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}") + commit_link=${commit_link//\//\\/} + sed -i -r "s/\*\*Commit:\*\*.+/\*\*Commit:\*\* \[$short_sha\]\($commit_link\) /" ./wiki/_Sidebar.md + + - name: push-changes + working-directory: ./wiki + # In case nothing changed + continue-on-error: true + run: | + git config user.name github-actions + git config user.email github-actions@github.com + git status + git add . + git commit -m "chore: sync references between wiki and project" + git push diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 04c19ad..5aa228d 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -4,7 +4,7 @@ on: - main # See: https://github.com/google-github-actions/release-please-action -name: Release Please +name: release-please permissions: contents: write @@ -13,8 +13,14 @@ permissions: jobs: release-please: runs-on: ubuntu-latest + + outputs: + release_created: ${{ steps.release.outputs.release_created }} + tag_name: ${{ steps.release.outputs.tag_name }} + steps: - uses: GoogleCloudPlatform/release-please-action@v3 + id: release with: # Change type and name depending on your repository # See: https://github.com/google-github-actions/release-please-action#release-types-supported @@ -30,3 +36,62 @@ jobs: {"type":"arch","section":"Architectur/Refactor","hidden":false}, {"type":"chore","section":"Miscellaneous","hidden":true} ] + + release-report: + runs-on: ubuntu-latest + container: + image: manuelhatzl/mantra:main + + needs: release-please + + outputs: + report: ${{ steps.report.outputs.report }} + + env: + BRANCH_NAME: ${{ github.base_ref || github.ref_name }} + release_created: ${{ needs.release-please.outputs.release_created }} + tag_name: ${{ needs.release-please.outputs.tag_name }} + + steps: + - uses: actions/checkout@v3 + if: ${{ env.release_created }} + with: + repository: 'mhatzl/evident-wiki' + path: './req_folder' + sparse-checkout: 5-Requirements + + - name: report + id: report + if: ${{ env.release_created }} + run: | + mantra release --branch=$BRANCH_NAME --release-tag=${{ env.tag_name }} --wiki-url-prefix=https://github.com/mhatzl/evident/wiki --report-file=release_report.md ./req_folder + content=$(cat release_report.md) + content="${content//\'/\\\'}" + content="${content//\"/\\\"}" + echo "report<> $GITHUB_OUTPUT + echo "$content" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + + upload-report: + runs-on: ubuntu-latest + + needs: ["release-report", "release-please"] + + env: + release_created: ${{ needs.release-please.outputs.release_created }} + tag_name: ${{ needs.release-please.outputs.tag_name }} + report: ${{ needs.release-report.outputs.report }} + + steps: + - uses: actions/checkout@v3 + if: ${{ env.release_created }} + + - name: upload + if: ${{ env.release_created }} + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + report="$(echo '${{ env.report }}')" + echo "$report" >> release_report.md + cat release_report.md + gh release upload ${{ env.tag_name }} release_report.md