interthread/

lib.rs

//! # Intro
//!
//! This document covers the usage of the crate's macros, it does 
//! not delve into the detailed logic of the generated code.
//! 
//! For a comprehensive understanding of the underlying
//! concepts and implementation details of the Actor Model,  
//! it's recommended to read the article  [Actors with Tokio](https://ryhl.io/blog/actors-with-tokio/)
//! by Alice Ryhl ( also known as _Darksonn_ ) also a great 
//! talk by the same author on the same subject if a more 
//! interactive explanation is prefered 
//! [Actors with Tokio – a lesson in ownership - Alice Ryhl](https://www.youtube.com/watch?v=fTXuGRP1ee4)
//! (video).
//! This article not only inspired the development of the 
//! `interthread` crate but serves as foundation 
//! for the Actor Model implementation logic in it. 


//! ## What is an Actor ?
//!
//! Despite being a fundamental concept in concurrent programming,
//! defining exactly what an actor is can be ambiguous.
//! 
//! - *Carl Hewitt*, often regarded as the father of the Actor Model,
//! [The Actor Model](https://www.youtube.com/watch?v=7erJ1DV_Tlo) (video).
//! 
//! - Wikipidia [Actor Model](https://en.wikipedia.org/wiki/Actor_model)
//!  
//!
//! a quote from [Actors with Tokio](https://ryhl.io/blog/actors-with-tokio/):
//! 
//! > "The basic idea behind an actor is to spawn a 
//! self-contained task that performs some job independently
//! of other parts of the program. Typically these actors
//! communicate with the rest of the program through 
//! the use of message passing channels. Since each actor 
//! runs independently, programs designed using them are 
//! naturally parallel."
//! > - Alice Ryhl 
//!
//! ## What is the problem ?
//! 
//! To achieve parallel execution of individual objects 
//! within the same program, it is challenging due 
//! to the need for various types that are capable of 
//! working across threads. The main difficulty 
//! lies in the fact that as you introduce thread-related types,
//! you can quickly lose sight of the main program 
//! idea as the focus shifts to managing thread-related 
//! concerns.
//!
//! It involves using constructs like threads, locks, channels,
//! and other synchronization primitives. These additional 
//! types and mechanisms introduce complexity and can obscure 
//! the core logic of the program.
//! 
//! 
//! ## Solution 
//! 
//! The [`actor`](./attr.actor.html) macro -  when applied to the 
//! implementation block of a given "MyActor" object,
//! generates additional Struct types  
//! that enable communication between threads.
//! 
//! A notable outcome of applying this macro is the 
//! creation of the `MyActorLive` struct ("ActorName" + "Live"),
//! which acts as an interface/handle to the `MyActor` object.
//! `MyActorLive` retains the exact same public method signatures
//! as `MyActor`, allowing users to interact with the actor as if 
//! they were directly working with the original object.
//! 
//! ### Examples
//! 
//! 
//! Filename: Cargo.toml
//! 
//!```text
//![dependencies]
//!interthread = "3.1.0"
//!oneshot     = "0.1.11" 
//!```
//! 
//! Filename: main.rs
//!```rust no_run
//!pub struct MyActor {
//!    value: i8,
//!}
//!
//!#[interthread::actor] 
//!impl MyActor {
//!
//!    pub fn new( v: i8 ) -> Self {
//!       Self { value: v } 
//!    }
//!    pub fn increment(&mut self) {
//!        self.value += 1;
//!    }
//!    pub fn add_number(&mut self, num: i8) -> i8 {
//!        self.value += num;
//!        self.value
//!    }
//!    pub fn get_value(&self) -> i8 {
//!        self.value
//!    }
//!}
//!
//!fn main() {
//!
//!    let actor = MyActorLive::new(5);
//!
//!    let mut actor_a = actor.clone();
//!    let mut actor_b = actor.clone();
//!
//!    let handle_a = std::thread::spawn( move || { 
//!    actor_a.increment();
//!    });
//!
//!    let handle_b = std::thread::spawn( move || {
//!    actor_b.add_number(5);
//!    });
//!
//!    let _ = handle_a.join();
//!    let _ = handle_b.join();
//!
//!    assert_eq!(actor.get_value(), 11)
//!}
//!
//! ```
//! 
//! An essential point to highlight is that when invoking 
//! `MyActorLive::new`, not only does it return an instance 
//! of `MyActorLive`, but it also spawns a new thread that 
//! contains an instance of `MyActor` in it. 
//! This introduces parallelism to the program.
//! 
//! The code generated by the [`actor`](./attr.actor.html) takes 
//! care of the underlying message routing and synchronization, 
//! allowing developers to rapidly prototype their application's
//! core functionality. This fast sketching capability is
//! particularly useful when exploring different design options, 
//! experimenting with concurrency models, or implementing 
//! proof-of-concept systems. Not to mention, the cases where 
//! the importance of the program lies in the result of its work 
//! rather than its execution.
//!
//! 
//! # SDPL Framework
//! 
//! 
//!  The code generated by the [`actor`](./attr.actor.html) macro 
//! can be divided into four more or less important but distinct 
//! parts: [`script`](#script) ,[`direct`](#direct), 
//! [`play`](#play), [`live`](#live) .
//! 
//!  This categorization provides an intuitive 
//! and memorable way to understand the different aspects 
//! of the generated code.
//! 
//! Expanding the above example, uncomment the [`example`](./attr.example.html)
//! placed above the `main` function, go to `examples/inter/main.rs` in your 
//! root directory and find `MyActor` along with additional SDPL parts :
//! 
//! # `script`
//! 
//!  Think of script as a message type definition.
//! 
//!  The declaration of an `ActorName + Script` enum, which is 
//! serving as a collection of variants that represent 
//! different messages that may be sent across threads through a
//! channel. 
//! 
//!  Each variant corresponds to a struct with fields
//! that capture the input and/or output parameters of 
//! the respective public methods of the Actor.
//!  
//! 
//! ```rust no_run
//! 
//! pub enum MyActorScript {
//!     Increment {},
//!     AddNumber { num: i8, inter_send: oneshot::Sender<i8> },
//!     GetValue { inter_send: oneshot::Sender<i8> },
//! }
//! 
//! ```
//! 
//! > **Note**: Method `new` not included as a variant in the `script`. 
//! 
//! 
//! # direct
//! The implementation block of `script`struct, specifically 
//! the `direct` method which allows 
//! for direct invocation of the Actor's methods by mapping 
//! the enum variants to the corresponding function calls.
//! 
//! 
//!```rust no_run
//!impl MyActorScript {
//!    pub fn direct(self, actor: &mut MyActor) {
//!        match self {
//!            MyActorScript::Increment {} => {
//!                actor.increment();
//!            }
//!            MyActorScript::AddNumber { num, inter_send } => {
//!                inter_send
//!                    .send(actor.add_number(num))
//!                    .unwrap_or_else(|_error| {
//!                        core::panic!(
//!                            "'MyActorScript::AddNumber.direct'. Sending on a closed channel."
//!                        )
//!                    });
//!            }
//!            MyActorScript::GetValue { inter_send } => {
//!                inter_send
//!                    .send(actor.get_value())
//!                    .unwrap_or_else(|_error| {
//!                        core::panic!(
//!                            "'MyActorScript::GetValue.direct'. Sending on a closed channel."
//!                        )
//!                    });
//!            }
//!        }
//!    }
//!}
//!```
//! 
//! # play
//! The implementation block of `script`struct, specifically 
//! the `play` associated (static) method responsible for 
//! continuously receiving `script` variants from 
//! a dedicated channel and `direct`ing them.
//! 
//! Also this function serves as the home for the Actor itself.
//! 
//! 
//!```rust no_run
//!impl MyActorScript { 
//!    pub fn play(receiver: std::sync::mpsc::Receiver<MyActorScript>, 
//!               mut actor: MyActor) {
//!        while let std::result::Result::Ok(msg) = receiver.recv() {
//!            msg.direct(&mut actor);
//!        }
//!        eprintln!("MyActor the end ...");
//!    }
//!}
//!``` 
//! 
//! When using the [`edit`](./attr.actor.html#edit) argument in the [`actor`](./attr.actor.html) 
//! macro, such as 
//! 
//!```rust no_run
//!#[interthread::actor(edit(script(imp(play))))]
//!``` 
//! 
//! it allows for manual implementation of the `play` part, which 
//! gives the flexibility to customize and modify 
//! the behavior of the `play` to suit any requared logic.
//! 
//! 
//! 
//! # live
//! A struct `ActorName + Live`, which serves as an interface/handler 
//! replicating the public method signatures of the original Actor.
//! 
//! Invoking a method on a live instance, it's triggering the eventual 
//! invocation of the corresponding method within the Actor. 
//! 
//! The special method of `live` method `new`  
//! - initiates a new channel
//! - initiates an instace of the Actor
//! - spawns the `play` component in a separate thread 
//! - returns an instance of `Self`
//! 
//! 
//! ```rust no_run 
//! 
//!#[derive(Clone)]
//!pub struct MyActorLive {
//!    sender: std::sync::mpsc::Sender<MyActorScript>,
//!}
//!impl MyActorLive {
//!    pub fn new(v: i8) -> Self {
//!        let actor = MyActor::new(v);
//!        let (sender, receiver) = std::sync::mpsc::channel();
//!        std::thread::spawn(move || { MyActorScript::play(receiver, actor) });
//!        Self { sender }
//!    }
//!    pub fn increment(&mut self) {
//!        let msg = MyActorScript::Increment {};
//!        let _ = self
//!            .sender
//!            .send(msg)
//!            .expect("'MyActorLive::method.send'. Channel is closed!");
//!    }
//!    pub fn add_number(&mut self, num: i8) -> i8 {
//!        let (inter_send, inter_recv) = oneshot::channel();
//!        let msg = MyActorScript::AddNumber {
//!            num,
//!            inter_send,
//!        };
//!        let _ = self
//!            .sender
//!            .send(msg)
//!            .expect("'MyActorLive::method.send'. Channel is closed!");
//!        inter_recv
//!            .recv()
//!            .unwrap_or_else(|_error| {
//!                core::panic!("'MyActor::add_number' from inter_recv. Channel is closed!")
//!            })
//!    }
//!    pub fn get_value(&self) -> i8 {
//!        let (inter_send, inter_recv) = oneshot::channel();
//!        let msg = MyActorScript::GetValue {
//!            inter_send,
//!        };
//!        let _ = self
//!            .sender
//!            .send(msg)
//!            .expect("'MyActorLive::method.send'. Channel is closed!");
//!        inter_recv
//!            .recv()
//!            .unwrap_or_else(|_error| {
//!                core::panic!("'MyActor::get_value' from inter_recv. Channel is closed!")
//!            })
//!    }
//!}
//! 
//! ```
//! The methods of `live` type have same method signature
//! as Actor's own methods 
//! - initiate a `oneshot` channel
//! - create a `msg` specific `script` variant
//! - send the `msg` via `live`'s channel 
//! - receive and return the output if any   
//! 
//! # Panics
//! 
//! The model will panic if an attempt is made to send or 
//! receive on the channel after it has been dropped. 
//! Generally, such issues are unlikely to occur, but 
//! if the `interact` option is used, it introduces a 
//! potential scenario for encountering this situation.
//!  
//! 
//! # Macro Implicit Dependencies
//!
//! The [`actor`](./attr.actor.html) macro generates code
//! that utilizes channels for communication. However, 
//! the macro itself does not provide any channel implementations.
//! Therefore, depending on the libraries used in your project, 
//! you may need to import additional crates.
//!
//!### Crate Compatibility
//!<table>
//!  <thead>
//!    <tr>
//!      <th>lib</th>
//!      <th><a href="https://docs.rs/oneshot">oneshot</a></th>
//!      <th><a href="https://docs.rs/async-channel">async_channel</a></th>
//!    </tr>
//!  </thead>
//!  <tbody>
//!    <tr>
//!      <td>std</td>
//!      <td style="text-align: center;">&#10003;</td>
//!      <td style="text-align: center;"><b>-</b></td>
//!    </tr>
//!    <tr>
//!      <td><a href="https://crates.io/crates/smol">smol</a></td>
//!      <td style="text-align: center;">&#10003;</td>
//!      <td style="text-align: center;">&#10003;</td>
//!    </tr>
//!    <tr>
//!      <td><a href="https://docs.rs/tokio">tokio</a></td>
//!      <td style="text-align: center;"><b>-</b></td>
//!      <td style="text-align: center;"><b>-</b></td>
//!    </tr>
//!    <tr>
//!      <td><a href="https://crates.io/crates/async-std">async-std</a></td>
//!      <td style="text-align: center;">&#10003;</td>
//!      <td style="text-align: center;"><b>-</b></td>
//!    </tr>
//!  </tbody>
//!</table>
//!
//! 
//!>**Note:** The table shows the compatibility of 
//!>the macro with different libraries, indicating whether 
//!>the dependencies are needed (✔) or not. 
//!>The macros will provide helpful messages indicating 
//!>the necessary crate imports based on your project's dependencies.
//!
//! 
//! Checkout `interthread` on [![GitHub](https://img.shields.io/badge/GitHub-%2312100E.svg?&style=plastic&logo=GitHub&logoColor=white)](https://github.com/NimonSour/interthread)
//! 


mod use_macro;
mod write;
mod file;
mod check;
mod error;
mod parse;
mod model;

static INTERTHREAD: &'static str            = "interthread";
static INTER_EXAMPLE_DIR_NAME: &'static str = "INTER_EXAMPLE_DIR_NAME";
static INTER: &'static str                  = "inter";
// static WEB_ACTOR: &'static str              = "web_actor";

static ACTOR: &'static str                  = "actor";
static FAMILY: &'static str                 = "family";

static EXAMPLE: &'static str                = "example";
static EXAMPLES: &'static str               = "examples";

const RWLOCK: &str = "RwLock";
const MUTEX: &str  = "Mutex";
const ARC: &str    = "Arc";

// vars
static INTER_SEND: &'static str = "inter_send";
static INTER_RECV: &'static str = "inter_recv";

// Some of Attributes Arguments
static EDIT: &'static str = "edit";
static FILE: &'static str = "file";



#[cfg(windows)]
const LINE_ENDING: &'static str = "\r\n";
#[cfg(not(windows))]
const LINE_ENDING: &'static str = "\n";

/// # Code transparency and exploration
///  
/// [`example`](./attr.example.html) simplifies exploring and interacting with 
/// expanded macro-generated code. It generates example files with expanded 
/// content of `interthread` macros, making it easy for developers to debug, test, and experiment.
/// 
/// Consider a macro [`actor`](./attr.actor.html)  inside the project 
/// in `src/my_file.rs`.
/// 
///Filename: my_file.rs 
///```rust no_run
/// 
///pub struct MyActor;
///
/// // you can have "example" macro in the same file
/// // #[interthread::example(path="src/my_file.rs")]
///
///#[interthread::actor]
///impl MyActor {
///    pub fn new(value: u32) -> Self {Self}
///}
///
///```
/// 
///Filename: main.rs 
///```rust no_run
///#[interthread::example(path="src/my_file.rs")]
///fn main(){
///}
///
///```
/// 
/// The macro will create and write to `examples/inter/my_file.rs`
/// the content of `src/my_file.rs` with the 
/// [`actor`](./attr.actor.html) macro expanded.
/// 
/// 
///```text
///my_project/
///├── src/
///│  ├── my_file.rs      <---  macro "actor" 
///|  |
///│  └── main.rs         <---  macro "example" 
///|
///├── examples/          
///   ├── ...
///   └── inter/      
///      ├── my_file.rs   <--- expanded "src/my_file.rs"  
///```
///
/// When specifying the `main` argument 
/// in the `example` macro. It generates two files within 
/// the `examples/inter` directory: the expanded code file 
/// and an additional `main.rs` file. 
///
///```rust no_run
///#[example(main,path="my_file.rs")]
///```
///
/// This option is particularly useful for debugging and experimentation. 
/// It allows developers to quickly run and interact with the generated code by executing:
///
///```terminal
///$ cargo run --example inter
///```
///
/// The expanded code file will be located at 
/// `examples/inter/my_file.rs`, while the `main.rs` file 
/// serves as an entry point for running the example.
/// 
/// ## Configuration Options  
///```text 
/// 
///#[interthread::example( 
///
///        main | mod *
/// 
///        path = "path/to/file.rs"  
///
///        expand(actor,family) *
/// )]
/// 
/// * - default   
/// 
///```
/// 
/// # Arguments
/// 
/// - [`path`](#path)
/// 
/// - [`expand`](#expand) (default)
/// 
/// # path
/// 
/// The `path` argument is a required parameter of the [`example`](./attr.example.html) macro.
/// It expects the path to the file that needs to be expanded.
/// 
/// This argument is essential as it specifies the target file 
/// for code expansion.
/// 
/// [`example`](./attr.example.html) macro can be 
/// placed on any item in any file within your `src` directory.
/// 
///  
/// # expand
/// 
/// This argument allows the user to specify which 
/// `interthread` macros to expand. 
/// 
/// By default, the value of `expand` includes 
/// the [`actor`](./attr.actor.html) and 
/// [`family`](./attr.family.html) macros.
/// 
/// For example, if you want to expand only the
/// [`actor`](./attr.actor.html) macro in generated 
/// example code, you can use the following attribute:
/// 
/// ```rust no_run
/// #[example(path="my_file.rs",expand(actor))]
/// ```
/// This will generate an example code file that includes 
/// the expanded code of the [`actor`](./attr.actor.html) macro,
/// while excluding other macros like 
/// [`family`](./attr.family.html).
/// 
 

#[proc_macro_error::proc_macro_error]
#[proc_macro_attribute]
pub fn example( attr: proc_macro::TokenStream, _item: proc_macro::TokenStream ) -> proc_macro::TokenStream {

    let nested  = syn::parse_macro_input!(attr with syn::punctuated::Punctuated::<syn::Meta,syn::Token![,]>::parse_terminated); 
    let mut eaa   = model::attribute::ExampleAttributeArguments::from(nested);

    let (file, lib)  = file::expand_macros(&eaa.get_path(),&eaa.expand);

    let some_lib = if eaa.main { Some(lib)} else { None };

    let path = write::example_show(file, &eaa.get_path(), some_lib );

    let msg = format!("The file has been SUCCESSFULLY created at {}",path.to_string_lossy());
    let note  = "To avoid potential issues and improve maintainability, it is recommended to comment out the macro after its successful execution. To proceed, please comment out the macro and re-run the compilation.";
    
    proc_macro_error::abort!( proc_macro2::Span::call_site(),msg; note = note);
    
}


/// ## Evolves a regular object into an actor
/// 
/// The macro is placed upon an implement block of an object
/// (`struct` or `enum`),
/// which has a public or restricted method named `new` returning  `Self`.
///
/// In case if the initialization could potentially fail, 
/// the method can be named `try_new` 
/// and return `Option<Self>` or `Result<Self>`.
/// 
/// The macro will copy method signatures from all 
/// public methods with receivers `&self` or `&mut self`
/// and static methods.
/// 
/// The model is primarily designed to work for public methods with 
/// borrowed receivers (e.g., `&self` or `&mut self`) however
/// `Self`-consuming receiver (e.g., `self`) can be incorporated
/// see [`What Does a Self-Consuming Method Mean for the Model`](#self-consuming-methods)
/// 
/// If only a subset of methods is required to be 
/// accessible across threads, split the `impl` block 
/// into two parts. By applying the macro to a specific block, 
/// the macro will only consider the methods within that block, also see options
/// [`include-exclude`](#include-exclude).
/// 
/// ## Configuration Options
///```text 
/// 
///#[interthread::actor( 
///    
///    channel = 0 * 
///              n (usize)
///
///        lib = "std" *
///              "smol"
///              "tokio"
///              "async_std"
///
///        edit( 
///             script(..)
///             live(..)
///            ) 
///
///        file = "path/to/current/file.rs"
///        
///        name = "" 
///
///        show
///       
///       include | exclude  
///        
///       debut
/// 
///    interact
///)]
///
///*  -  default 
///
///
///```
///  
/// # Arguments
///  
///
/// - [`channel`](#channel)
/// - [`lib`](#lib) 
/// - [`edit`](#edit)
/// - [`file`](#file)
/// - [`name`](#name)
/// - [`show`](#show)
/// - [`include|exclude`](#include|exclude)
/// - [`debut`](#debut)
/// - [`interact`](#interact)
///
/// 
/// 
/// # channel
///
/// The `channel` argument specifies the type of channel. 
///   
/// - `0`  (default)
/// - [`usize`] ( buffer size)
/// 
/// The two macros
/// ```rust no_run
/// #[actor]
/// ```
/// and
/// ```rust no_run
/// #[actor(channel=0)]
/// ```
/// are in fact identical, both specifying same unbounded channel.
/// 
/// When specifying an [`usize`] value for the `channel` argument 
/// in the [`actor`](./attr.actor.html) macro, such as 
/// ```rust no_run
/// #[actor(channel=4)]
/// ```
/// the actor will use a bounded channel with a buffer size of 4.
/// This means that the channel can hold up to 4 messages in its 
/// buffer before blocking/suspending the sender.
///
/// Using a bounded channel with a specific buffer size allows 
/// for control over the memory usage and backpressure behavior 
/// of the model. When the buffer is full, any further attempts 
/// to send messages will block/suspend until there is available space. 
/// This provides a natural form of backpressure, allowing the 
/// sender to slow down or pause message production when the 
/// buffer is near capacity.
/// 
/// # lib
///
/// The `lib` argument specifies the 'async' library to use.
///
/// - `"std"` (default)
/// - `"smol"`
/// - `"tokio"`
/// - `"async_std"`
///
///## Examples
///```rust no_run
///use interthread::actor;
///
///struct MyActor;
///
///#[actor(channel=10, lib ="tokio")]
///impl MyActor{
///    pub fn new() -> Self{Self}
///}
///#[tokio::main]
///async fn main(){
///    let my_act = MyActorLive::new();
///}
///```
/// 
/// # edit
///
/// The `edit` argument specifies the available editing options.
/// When using this argument, the macro expansion will 
/// **exclude** the code related to `edit` options 
/// allowing the user to manually implement and 
/// customize those parts according to their specific needs.
/// 
/// 
/// The SDPL Model encompasses two main structs, namely `ActorScript` and `ActorLive`.
/// Within the `edit` statement, these are referenced as `script` 
/// and `live` respectively.
/// 
/// Each struct comprises three distinct sections: 
/// - `def` - definition
/// - `imp` - implementation block
/// - `trt` - implemented traits
///
/// ```rust no_run
/// edit(
///     script(
///         def,     // <- script definition
///         imp(..), // <- list of methods in impl block
///         trt(..)  // <- list of traits
///     ),
///     
///     live(
///         def,     // <- live definition
///         imp(..), // <- list of methods in impl block
///         trt(..)  // <- list of traits
///     )
/// )
/// ```
/// 
/// So this option instructs the macro to:
/// 
/// - Exclude specified sections of code from the generated model.
/// 
/// Examples:
/// - `edit(script)`: Excludes the entire Script enum.
/// - `edit(live(imp))`: Excludes the entire implementation block of the Live struct.
/// - `edit(live(def, imp(new)))`: Excludes both the definition of the Live struct and the method 'new.'
/// - `edit(script(imp(play)), live(imp(new)))`: Excludes the 'play' method from the Script enum and the 'new' method from the Live struct.
/// 
/// Exclusion of code becomes necessary when the user has already 
/// customized specific sections of the model. 
/// To facilitate the exclusion of parts from the generated 
/// model and enable printing them to the file for further 
/// user customization, consider the [`file`](#file) option,
/// which works in conjunction with the `edit` option.
/// 
/// # file
/// This argument is designed to address proc macro file blindness. It requires 
/// a string path to the current file as its value. Additionally, within the `edit` argument,
/// one can use the keyword `file` to specify which portion of the excluded code should be written
/// to the current module, providing the user with a starting point for customization.
///  
///  
/// ## Examples
/// 
/// Filename: main.rs
/// 
///```rust no_run
///pub struct MyActor(u8);
///
///#[interthread::actor(
///    file="src/main.rs",
///    edit(live(imp( file(increment) )))
///)]  
///
///impl MyActor {
///
///    pub fn new() -> Self {Self(0)}
///
///    pub fn increment(&mut self){
///        self.0 += 1;
///    }
///}
///```
/// This is the output after saving:
/// 
/// ```rust no_run
///
///pub struct MyActor(u8);
///
///#[interthread::actor(
///    file="src/main.rs",
///    edit(live(imp(increment)))
///)]  
///
///impl MyActor {
///
///    pub fn new() -> Self {Self(0)}
///
///    pub fn increment(&mut self){
///        self.0 += 1;
///    }
///}
///
/// //++++++++++++++++++[ Interthread  Write to File ]+++++++++++++++++//
/// // Object Name   : MyActor  
/// // Initiated By  : #[interthread::actor(file="src/main.rs",edit(live(imp(file(increment)))))]  
/// 
/// 
/// impl MyActorLive {
///     pub fn increment(&mut self) {
///         let msg = MyActorScript::Increment {};
///         let _ = self
///             .sender
///             .send(msg)
///             .expect("'MyActorLive::method.send'. Channel is closed!");
///     }
/// }
/// 
/// // *///.............[ Interthread  End of Write  ].................//
///
/// ```
/// 
/// To specify the part of your model that should be written to 
/// the file, simply enclose it within `file(..)` inside the `edit` 
/// argument. Once the desired model parts are written, 
/// the macro will automatically clean the `file` arguments, 
/// adjusting itself to the correct state.
/// 
/// 
/// Attempting to nest `file` arguments like: 
/// ```rust no_run
/// edit( file( script( file( def))))
/// ```
/// will result in an error.
/// 
/// 
/// A special case of the `edit` and `file` conjunction, 
/// using `edit(file)` results in the macro being replaced with 
/// the generated code on the file.
/// 
/// 
/// 
///  > **Note:** While it is possible to have multiple actor macros
/// within the same module, only one of the macro can have `file` 
/// active arguments (`file` within `edit`) at a time.
/// 
/// 
/// # name
/// 
/// The `name` attribute allows developers to provide a 
/// custom name for `actor`, overriding the default 
/// naming conventions of the crate. This can be useful 
/// when there are naming conflicts or when a specific 
/// naming scheme is desired.  
/// 
/// - "" (default): No name specified
///
/// ## Examples
///```rust no_run
///use interthread::actor;
/// 
///pub struct MyActor;
/// 
///#[actor(name="OtherActor")]
///impl MyActor {
///
///   pub fn new() -> Self {Self}
///}
///fn main () {
///   let other_act = OtherActorLive::new();
///}
///```
/// 
/// 
/// # show 
/// 
/// The `show` option is particularly useful for users who are just starting to 
/// work with this crate. When enabled, the model will generate doc comments 
/// for every block of code it produces, containing the code produce, with the 
/// exception of traits, which are simply listed.
/// 
/// Your text editor handles the rest.
/// 
/// By default, the model carries over the user's documentation comments from 
/// the actor object methods. 
/// Enabling `show` will add additional information, detailing the exact 
/// code generated by the model.
/// Try hovering over `AaLive` and its `new` method to see the generated code.
/// 
///  ## Examples
///```rust no_run
///use interthread::actor;
///pub struct Aa;
///  
///#[actor(show)]
///impl Aa {
///    /// This is my comment
///    /// Creates a new instance of AaLive.
///    pub fn new() -> Self { Self{} }
/// 
///}
///
///fn main() {    
///    let bb = AaLive::new(); 
///}
///
///```
/// Disable `show` to avoid performance overhead and excessive code generation, 
/// when the option is no longer needed.
/// 
///  
/// # include-exclude
/// The include and exclude options are mutually exclusive filters that control 
/// which methods are included in the generated model. Only one of these 
/// options can be used at a time.
/// 
/// Usage
/// 
/// - include: Specifies the methods to include in the generated model.
/// - exclude: Specifies the methods to exclude from the generated model.
/// 
/// For a given list of actor's methods `[a, b, c, d]`:
/// 
/// - Using `include(a)` will generate a model that only includes the method `a`.
/// - Using `exclude(a,b)` will generate a model that includes the methods `c`, and `d`.
/// 
/// ```rust no_run
/// #[interthread::actor( exclude(foo,bar))]
/// ```
/// 
/// # debut
/// 
/// The generated code is designed to 
/// compile successfully on Rust versions as early as 1.63.0.
/// 
/// When declared `debut`, the following additions and implementations 
/// are generated:
/// 
/// 
/// Within the [`live`](index.html#live) struct definition, the following
/// fields are generated:
/// 
/// - `pub debut: std::time::SystemTime`
/// - `pub name: String`
/// 
/// The following traits are implemented for the [`live`](index.html#live) struct:
/// 
/// - `PartialEq`
/// - `PartialOrd`
/// - `Eq`
/// - `Ord`
/// 
/// These traits allow for equality and ordering 
/// comparisons based on the `debut`value.
/// The `name` field is provided for user needs only and is not 
/// taken into account when performing comparisons. 
/// It serves as a descriptive attribute or label 
/// associated with each instance of the live struct.
/// 
/// In the [`script`](index.html#script) struct implementation block, which 
/// encapsulates the functionality of the model,
/// a static method named `debut` is generated. This 
/// method returns the current system time and is commonly 
/// used to set the `debut` field when initializing 
/// instances of the [`live`](index.html#live) struct.
/// 
/// 
/// Use macro [`example`](./attr.example.html) to see the generated code.
/// 
/// 
/// ## Examples
///  
///```rust no_run
///use std::thread::spawn;
///pub struct MyActor ;
///
///#[interthread::actor( debut )] 
///impl MyActor {
///    pub fn new() -> Self { Self{} } 
///}
///fn main() {
///
///    let actor_1 = MyActorLive::new();
///
///    let handle_2 = spawn( move || { 
///        MyActorLive::new()
///    });
///    let actor_2 = handle_2.join().unwrap();
///
///    let handle_3 = spawn( move || {
///        MyActorLive::new()
///    });
///    let actor_3 = handle_3.join().unwrap();
///    
///    // they are the same type objects
///    // but serving differrent threads
///    // different actors !   
///    assert!(actor_1 != actor_2);
///    assert!(actor_2 != actor_3);
///    assert!(actor_3 != actor_1);
///
///    // since we know the order of invocation
///    // we correctly presume
///    assert_eq!(actor_1 > actor_2, true );
///    assert_eq!(actor_2 > actor_3, true );
///    assert_eq!(actor_3 < actor_1, true );
///
///    // but if we check the order by `debute` value
///    assert_eq!(actor_1.debut < actor_2.debut, true );
///    assert_eq!(actor_2.debut < actor_3.debut, true );
///    assert_eq!(actor_3.debut > actor_1.debut, true );
///    
///    // This is because the 'debut' 
///    // is a time record of initiation
///    // Charles S Chaplin (1889)
///    // Keanu Reeves      (1964)
///
///
///    // we can count `live` instances for 
///    // every model
///    use std::sync::Arc;
///    let mut a11 = actor_1.clone();
///    let mut a12 = actor_1.clone();
///
///    let mut a31 = actor_3.clone();
///
///    assert_eq!(Arc::strong_count(&actor_1.debut), 3 );
///    assert_eq!(Arc::strong_count(&actor_2.debut), 1 );
///    assert_eq!(Arc::strong_count(&actor_3.debut), 2 );
///            
///
///    // or use getter `count`                 
///    assert_eq!(actor_1.inter_get_count(), 3 );
///    assert_eq!(actor_2.inter_get_count(), 1 );
///    assert_eq!(actor_3.inter_get_count(), 2 );
///    
///
///    use std::time::SystemTime;
///
///    // getter `debut` to get its timestamp   
///    let _debut1: SystemTime = actor_1.inter_get_debut();
///
///            
///    // the name field is not taken 
///    // into account when comparison is
///    // perfomed       
///    assert!( a11 == a12);
///    assert!( a11 != a31);
///
///    a11.name = String::from("Alice");
///    a12.name = String::from("Bob");
///
///    a31.name = String::from("Alice");
///
///    assert_eq!(a11 == a12, true );
///    assert_eq!(a11 != a31, true );
///
///    // setter `name` accepts any ToString  
///    a11.inter_set_name('t');
///    a12.inter_set_name(84u32);
///    a31.inter_set_name(3.14159);
///
///    // getter `name`                      
///    assert_eq!(a11.inter_get_name(), "t" );
///    assert_eq!(a12.inter_get_name(), "84" );
///    assert_eq!(a31.inter_get_name(), "3.14159" );
///
///}
///``` 
/// 
/// 
/// 
/// 
/// Using `debut` will generate fore additional
///methods in `live` implement block:
/// 
/// 1. `inter_set_name(s: ToString)`: Sets the value of the 
/// name field.
/// 2. `inter_get_name() -> &str`: Retrieves the value of the 
/// name field.
/// 3. `inter_get_debut() -> std::time::SystemTime`: Retrieves
/// the value of the debut field, which represents a timestamp.
/// 4. `inter_get_count() -> usize`: Provides the strong 
/// reference count for the debut field.
///  
///This convention allows 
///- easy identification in text editor methods that 
///solely manipulate the internal state of the live struct and/or 
///methods that are added by the `interthread` macros
///- it mitigates the risk of potential naming conflicts in case if there
///is or will be a custom method `get_name`
///-  helps the macro  identify methods that are intended 
///to be used within its context (see [`interact`](#interact))
///
/// # interact
/// 
/// The `interact` option is designed to provide the model with 
/// comprehensive non-blocking functionality, along with convenient 
/// internal getter calls to access the state of the `live` instance via
/// so called `inter variables` in actor methods.
/// 
/// ### Rules and Definitions
/// 
/// 1. The interact variables should be prefixed with `inter_`.
/// 2. Special interact variables are `inter_send` and `inter_recv`.
/// 3. Declaring an `inter_variable_name : Type`, within actor method
/// arguments implies that the `live` instance has a method 
/// `fn inter_get_variable_name(&self) -> Type` which takes no arguments 
/// and returns the `Type`. Exceptions to this rule apply for special 
/// interact variables.
/// 4. If the actor method returns a type, accessing special interact variables
/// is not allowed. 
/// 5. Only one end of special interact variables can be accessed at a time.
///  
/// 
/// 
/// The primary purpose of `interact` is to leverage its oneshot `inter_send` 
/// and `inter_recv` ends. This allows for
/// a form of non-blocking behavior: one end of the channel will be directly 
/// sent into the respective method, while the other end will be returned 
/// from the live instance method. 
/// 
/// 
/// ## Examples
/// ```rust no_run
/// 
///pub struct MyActor;
///
///// opt `interact`
///#[interthread::actor( interact )] 
///impl MyActor {
///
///    pub fn new() -> Self { Self{} } 
///
///    // oneshot channel can be accessed 
///    // in methods that do not return 
///    pub fn heavy_work(&self, inter_send: oneshot::Sender<u8>){
///
///        std::thread::spawn(move||{
///            // do some havy computation
///            let _ = inter_send.send(5);
///        });
///    }
///}
///
///fn main () {
///
///    let actor = MyActorLive::new();
/// 
///    // the signature is different
///    let recv: oneshot::Receiver<u8> = actor.heavy_work(); 
///    let int = recv.recv().unwrap();
///
///    assert_eq!(5u8, int);
///}
/// 
/// ``` 
///  
/// While a method that does not return a type (see original `heavy_work`) 
/// typically does not require a oneshot channel, the 
/// model will accommodate the user's request by instantiating 
/// a channel pair. 
/// 
///```rust no_run
/// 
///pub fn heavy_work(&self) -> oneshot::Receiver<u8> {
///    let (inter_send, inter_recv) = oneshot::channel::<u8>();
///    let msg = MyActorScript::HeavyWork {
///        input: (inter_send),
///    };
///    let _ = self
///        .sender
///        .send(msg)
///        .expect("'MyActorLive::method.send'. Channel is closed!");
///    inter_recv
///}
///``` 
/// 
/// 
/// Also `interact` will detect interact variables in actor methods 
/// and subsequently call required getters within respective 
/// method of the `live` instance.
/// 
/// ## Examples
/// ```rust no_run
/// pub struct MyActor(String);
///
/// #[interthread::actor(debut, interact )] 
/// impl MyActor {
///
///     pub fn new() -> Self { Self("".to_string()) } 
///
///     // We know there is a getter `inter_get_name`
///     // Using argument `inter_name` we imply
///     // we want the return type of that getter
///     pub fn set_value(&mut self, inter_name: String){
///         self.0 = inter_name;
///     }
///     pub fn get_value(&self) -> String {
///         self.0.clone()
///     }
/// }
///
/// fn main () {
///
///     let mut actor = MyActorLive::new();
///
///     // Setting name for `live` instance
///     actor.inter_set_name("cloud");
///
///     // Setting actor's value now
///     // Note the signature, it's not the same  
///     actor.set_value();
///
///     assert_eq!("cloud".to_string(), actor.get_value());
/// }
/// ```
/// 
/// 
/// Here is how `live` instance method `set_value` will look like:
/// 
/// 
/// ```rust no_run
/// 
/// pub fn set_value(&mut self) {
///     let inter_name = self.inter_get_name();
///     let msg = MyActorScript::SetValue {
///         input: inter_name,
///     };
///     let _ = self
///         .sender
///         .send(msg)
///         .expect("'MyActorLive::method.send'. Channel is closed!");
/// }
/// 
/// ```
/// 
/// 
/// The signature has changed; it no longer takes arguments, as the 
/// getter call is happening inside providing the required type. 
/// It will work for any custom getter as long as it adheres to rule 3.
/// 
/// 
/// 
/// # Self Consuming Methods
/// 
/// For every method in an `Actor` object that consumes `Actor`, the model generates
/// a corresponding method in the `ActorLive` interface object that consumes both itself and the associated `Actor`. 
/// 
/// However, this design introduces challenges. The model inherently allows 
/// multiple `ActorLive` instances to send messages to a single `Actor` instance 
/// running in a separate thread. When an `ActorLive` instance consumes itself and 
/// its associated `Actor`, it effectively leaves other `ActorLive` instances without 
/// a functional `Actor`, disrupting the model operation.
/// 
/// To safely implement such self-consuming methods, the following conditions must be met:
/// 
/// ### Safety Conditions for Self-Consuming Methods
/// 
/// 1. **Enable the `debut` Option**
///    The model must have the `debut` option enabled (e.g., ```interthread::actor(debut)```), 
///    which allows it to track the number of active `ActorLive` instances.
/// 
/// 2. **Return a Valid Result Type**
///    Self-consuming methods must return one of the following types:
///    - `Option<T>`
///    - `Result<T, String>`
///    - `Result<T, &'static str>`
/// 
///    This requirement enables the model to inject a reference count check for `ActorLive`. 
///    If there are multiple active `ActorLive` instances, the method will return `Option::None` 
///    or `Result::Err`, indicating that the operation cannot proceed safely.
/// 
/// ### Limitations for Non-Compliant Methods
/// 
/// If a self-consuming method deviates from the above rules, the model enforces the following restrictions:
/// 
/// 1. **No Cloning**
///    The model will disallow the `Clone` trait for `ActorLive` object.
/// 
/// 2. **Private Visibility**
///    Self-consuming methods will be restricted to private visibility, making them inaccessible outside the module. 
/// 
/// ## Examples
/// 
/// Some examples of compliant self-consuming methods:
/// 
/// ```rust no_run
/// pub fn method(self, args, ...) -> Option<T>;
/// 
/// pub fn method(self, args, ...) -> Result<T, String>;
/// 
/// pub fn method(self, args, ...) -> Result<T, &'static str>;
/// ```
/// 
/// These examples illustrate the required return types and demonstrate how 
/// `self`-consuming methods can be safely integrated into the actor model.

#[proc_macro_error::proc_macro_error]
#[proc_macro_attribute]
pub fn actor( attr: proc_macro::TokenStream, item: proc_macro::TokenStream ) -> proc_macro::TokenStream {
    
    let item_impl = syn::parse_macro_input!(item as syn::ItemImpl);

    let nested  = syn::parse_macro_input!(attr with syn::punctuated::Punctuated::<syn::Meta,syn::Token![,]>::parse_terminated); 
    let mut aaa = model::attribute::ActorAttributeArguments::from(nested, crate::model::Mac::Actor);
    aaa.cross_check();

    check::channels_import( &aaa.lib );

    let edit_attr = aaa.edit.attr.clone();
    let mut model_sdpl = crate::model::generate_model( aaa, &item_impl);
    let (code,edit_sdpl) = model_sdpl.get_code_edit();
    if let Some( edit_attr ) = edit_attr {

        parse::edit_write( &edit_attr, &item_impl, edit_sdpl);
    }

    quote::quote!{
        #item_impl
        #code
    }.into()

}



/// ## A Wrapper for Managing Parallel ActorLive Instances
/// 
/// The `family` macro is designed as a convenient wrapper for initializing a 
/// set of `ActorLive` instances that operate in parallel, all serving the same Actor. 
/// The core idea behind the `family` concept can be summarized as `Exclusive Access to the Actor`.
/// 
/// 
/// ## Configuration Options
/// The `family` macro provides the same configuration options as the `actor` macro, 
/// ( with few exceptions ) and are inherited by `actor`'s declared within its body (e.g., `actor(first_name = "User", ...)`) which behaves exactly like the standalone `actor` macro. It allows defining individual `actor`s within the `family`. 
/// 
/// Options not explicitly specified in the `actor` configuration will be inherited from the `family` macro. For example, if `channel` is defined in family but omitted in `actor`, the channel value from `family` will be applied to the `actor`.
/// 
/// If the same-named options are present in both `family` and `actor`, they are treated independently.
/// 
/// ```text
/// #[interthread::family( 
///     
///   ~ channel = 0 * 
///               n (usize)
/// 
///         lib = std *
///               tokio
///               async_std
/// 
///         edit( 
///              def,
///              imp(..),
///              trt(..),
///             ) 
/// 
///         Mutex | RwLock *
///                
///         file = path/to/current/file.rs
///         
///         name = "" 
/// 
///         show
/// 
///         debut
/// 
///         actor(  
///                 first_name = "" 
/// 
///                 edit( 
///                     script(..)
///                     live(..)
///                     ) 
/// 
///                 include|exclude 
/// 
///                 show
/// 
///                 interact
///             )
/// 
/// )]
/// 
/// ~  -  override 
/// *  -  default 
/// ```
/// 
/// Options marked with `~` in the schema are inherited by default but can be overridden in the `actor` configuration.
/// 
/// The original `actor`'s  option `name` is different (`first_name` mandatory ) whereas `name` is 
/// optional part of `family`. The naming convention for an object named Actor is:
///     - for family  `Actor + Family` ( if not `name` specified )
///     - for actors `FirstName + Actor + Live|Script`
/// 
/// Consider the following example of a `family` macro:
/// ```text
/// #[interthread::family(
///     name = "MyActor",
///     Mutex, 
///     edit(file),
///     lib, 
///     channel,
///     debut,
/// 
///     actor(first_name = "User", include(foo)),  
///     actor(first_name = "Admin", include(foo, bar)),
/// )]
/// 
/// ```
/// will generate types named:
/// 
/// ```rust no_run
/// 
/// struct MyActorFamily {
///     pub user: UserMyActorLive,
///     pub admin: AdminMyActorLive,
/// }
/// // the script parts
/// UserMyActorScript 
/// AdminMyActorScript
/// 
/// ```
/// Behind the scenes, individual Actor Models are created for each member of the `family`,
/// sharing the same `Actor` object which is wrapped in either an `Arc<Mutex<Actor>>` 
/// or an `Arc<RwLock<Actor>>`, depending on the specified lock type.
/// 
/// Within the `Script::direct` method, immediately after the `Script` variant match, 
/// the `Actor` object is locked, and the corresponding method is invoked.
/// 
/// For developers seeking full control over the locking mechanism, the `family` 
/// macro provides a convention for defining static methods with a specific receiver. 
/// 
/// If a static method in the `Actor` implementation body uses a receiver 
/// named `actor` and its type matches the shared model type (`Arc<Mutex<Actor>>` or `Arc<RwLock<Actor>>`), 
/// the macro interprets this as a custom model method rather than a standard static method.
/// 
/// For example, consider the following method inside an Actor implementation:
/// ```rust no_run
/// impl Actor {
///     pub fn method(actor: &Arc<RwLock<Self>>, s: Type) -> Type {
///         let actor = actor.read().unwrap();
///         // Perform operations using the actor
///     }
/// }
/// ```
/// When processed by the macro, this method will be interpreted in `ActorLive` instance as:
/// 
/// ```rust no_run
/// impl ActorLive {
///     pub fn method(&self, s: Type) -> Type {
///         ...
///     }
/// }
/// ```
/// and processed correspondingly in `ActorScript`.
/// 
/// ### Supported Runtimes
/// The macro supports the following runtimes, each using its respective `Mutex` implementation:
/// 
/// 
/// |   Runtime  |    Mutex   |  RwLock |  
/// |:------------------------:|:----------:|:----------:|
/// | `std` (standard library) | `std::sync::Mutex`|`std::sync::RwLock` | 
/// | `tokio` | `tokio::sync::Mutex`|`tokio::sync::RwLock` | 
/// | `async-std` | `async_std::sync::Mutex`|`async_std::sync::RwLock` | 
/// 
/// The `smol` runtime does not support the `family` macro.


#[proc_macro_error::proc_macro_error]
#[proc_macro_attribute]
pub fn family( attr: proc_macro::TokenStream, item: proc_macro::TokenStream ) -> proc_macro::TokenStream {
    
    let item_impl = syn::parse_macro_input!(item as syn::ItemImpl);

    let nested  = syn::parse_macro_input!(attr with syn::punctuated::Punctuated::<syn::Meta,syn::Token![,]>::parse_terminated); 
    let mut aaa = model::attribute::ActorAttributeArguments::from(nested, crate::model::Mac::Family);
    aaa.cross_check();

    check::channels_import( &aaa.lib );

    let edit_attr = aaa.edit.attr.clone();
    let mut model_sdpl = crate::model::generate_model( aaa, &item_impl);
    let (code,edit_sdpl) = model_sdpl.get_code_edit();

    if let Some( edit_attr ) = edit_attr {

        parse::edit_write( &edit_attr, &item_impl, edit_sdpl);
    }

    quote::quote!{
        #item_impl
        #code
    }.into()

}