Arc Handle

https://docs.rs/arc-handle/latest/
Admin
Arc Handle is a Rust crate that provides an attribute macro for generating Arc-based handle wrappers...
Tokens:6,182
Snippets:15
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Rustdoc Help and Navigation

Source: https://docs.rs/arc-handle/latest/help

This section details the help dialog and keyboard shortcuts provided by rustdoc for navigating and searching documentation. It covers focusing the search field, navigating search results, expanding/collapsing sections, and advanced search tricks like prefixing searches with item kinds or searching by type signature.

```APIDOC
Rustdoc Help Dialog:

Keyboard Shortcuts:
  ? : Show this help dialog
  S / / : Focus the search field
  ↑ : Move up in search results
  ↓ : Move down in search results
  ← / → : Switch result tab (when results focused)
  ⏎ : Go to active search result
  + : Expand all sections
  - : Collapse all sections
  _ : Collapse all sections, including impl blocks

Search Tricks:
  Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given item kind.
  Accepted kinds are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.
  Search functions by type signature (e.g., `vec -> usize` or `-> vec` or `String, enum:Cow -> bool`).
  Look for items with an exact name by putting double quotes around your request: `"string"`.
  Look for functions that accept or return slices and arrays by writing square brackets (e.g., `-> [u8]` or `[] -> Option`).
  Look for items inside another one by searching for a path: `vec::Vec`.
```

--------------------------------

### Rustdoc Settings Configuration

Source: https://docs.rs/arc-handle/latest/settings

This section outlines various settings available for configuring the Rustdoc documentation generation. These settings control the appearance and behavior of the generated documentation, such as theme selection, auto-hiding elements, and font preferences.

```rust
// Theme selection
// light, dark, ayu, system preference
let theme = "dark";

// Preferred themes for light and dark modes
let preferred_light_theme = "ayu";
let preferred_dark_theme = "light";

// Auto-hide options
let auto_hide_item_contents = true;
let auto_hide_methods_documentation = false;
let auto_hide_trait_implementation_documentation = true;

// Search behavior
let direct_search_result = true;

// Code example display
let show_line_numbers = true;

// Navigation and layout
let hide_persistent_navigation_bar = false;
let hide_table_of_contents = true;
let hide_module_navigation = false;

// Font and text wrapping
let use_sans_serif_fonts = false;
let word_wrap_source_code = true;

// Keyboard shortcuts
let disable_keyboard_shortcuts = false;
```

--------------------------------

### Generate Async Method Implementations

Source: https://docs.rs/arc-handle/latest/src/arc_handle/lib.rs

This snippet demonstrates the process of generating asynchronous method implementations. It iterates through identified asynchronous methods, extracts their signatures (name, inputs, output), and constructs a new `async fn` block that calls the corresponding method on an inner object, appending `.await`.

```rust
    // Generate async method implementations
    let async_impl_methods = async_methods.iter().map(|method| {
        let method_name = &method.sig.ident;
        let inputs = &method.sig.inputs;
        let output = &method.sig.output;

        // Extract parameter names (skip &self)
        let param_names = method
            .sig
            .inputs
            .iter()
            .skip(1)
            .map(|arg| {
                if let syn::FnArg::Typed(pat_type) = arg {
                    if let syn::Pat::Ident(ident) = &*pat_type.pat {
                        &ident.ident
                    } else {
                        panic!("Unsupported parameter pattern");
                    }
                } else {
                    panic!("Unsupported parameter type");
                }
            })
            .collect::<Vec<_>>();

        quote! {
            pub async fn #method_name(#inputs) #output {
                self.inner.#method_name(#(#param_names),*).await
            }
        }
    });
```

--------------------------------

### Arc-Handle Proc Macro Usage

Source: https://docs.rs/arc-handle/latest/settings

This snippet demonstrates the basic usage of the arc-handle proc macro for generating Arc-based handle wrappers for traits. It requires the `arc-handle` crate and its associated dependencies.

```rust
use arc_handle::ArcHandle;

#[derive(ArcHandle)]
struct MyStruct {
    data: String,
}

fn main() {
    let my_struct = MyStruct { data: "Hello, world!".to_string() };
    let handle = MyStructHandle::new(my_struct);

    // Access data through the handle
    println!("{}", handle.data);
}
```

--------------------------------

### Generate Sync Method Implementations

Source: https://docs.rs/arc-handle/latest/src/arc_handle/lib.rs

This snippet illustrates the generation of synchronous method implementations. It processes synchronous methods, extracting their names, inputs, and outputs to create corresponding `fn` blocks that call the inner object's methods directly, without an `.await`.

```rust
    // Generate sync method implementations
    let sync_impl_methods = sync_methods.iter().map(|method| {
        let method_name = &method.sig.ident;
        let inputs = &method.sig.inputs;
        let output = &method.sig.output;

        // Extract parameter names (skip &self)
        let param_names = method
            .sig
            .inputs
            .iter()
            .skip(1)
            .map(|arg| {
                if let syn::FnArg::Typed(pat_type) = arg {
                    if let syn::Pat::Ident(ident) = &*pat_type.pat {
                        &ident.ident
                    } else {
                        panic!("Unsupported parameter pattern");
                    }
                } else {
                    panic!("Unsupported parameter type");
                }
            })
            .collect::<Vec<_>>();

        quote! {
            pub fn #method_name(#inputs) #output {
                self.inner.#method_name(#(#param_names),*)
            }
        }
    });
```

--------------------------------

### Arc-Handle Proc Macro

Source: https://docs.rs/arc-handle/latest/src/arc_handle/lib.rs

This proc macro generates Arc-based handle wrappers for traits, enabling thread-safe access to trait objects. It leverages other Rust macros for code generation.

```rust
#[proc_macro_derive(ArcHandle)]
pub fn arc_handle_derive(input: TokenStream) -> TokenStream {
    // Implementation details for generating Arc-based handle wrappers
    // ...
}
```

--------------------------------

### arc_handle Macro Implementation

Source: https://docs.rs/arc-handle/latest/src/arc_handle/lib.rs

The core implementation of the `arc_handle` attribute macro in Rust. It parses the input trait, renames it to `TraitImpl`, and prepares to generate a handle struct. It identifies and separates asynchronous and synchronous methods within the trait to facilitate the creation of appropriate delegate methods on the handle.

```rust
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, ItemTrait, Signature, TraitItem};

#[proc_macro_attribute]
pub fn arc_handle(_args: TokenStream, input: TokenStream) -> TokenStream {
    let mut input = parse_macro_input!(input as ItemTrait);

    let original_trait_name = &input.ident;
    let impl_trait_name = syn::Ident::new(
        &format!("{}Impl", original_trait_name),
        original_trait_name.span(),
    );
    let handle_name = original_trait_name.clone();

    // Rename the original trait to TraitImpl
    input.ident = impl_trait_name.clone();

    // Extract methods from the trait
    let mut async_methods = Vec::new();
    let mut sync_methods = Vec::new();

    for item in &input.items {
        if let TraitItem::Fn(method) = item {
            if is_async_method(&method.sig) {
                async_methods.push(method);
            } else {
                sync_methods.push(method);
            }
        }
    }

    // ... (rest of the macro implementation to generate the handle struct and methods) ...

    TokenStream::new() // Placeholder for actual output
}

// Helper function to check if a method is async (simplified)
fn is_async_method(sig: &Signature) -> bool {
    // In a real implementation, this would check for `async` keyword and potentially `async_trait` attributes.
    // For this example, we'll assume methods returning `impl Future` are async.
    // A more robust check would involve inspecting the return type more thoroughly.
    sig.asyncness.is_some()
}

```

--------------------------------

### Rust Macro for Generating Trait Handles

Source: https://docs.rs/arc-handle/latest/src/arc_handle/lib.rs

This snippet demonstrates a Rust macro used to generate a thread-safe handle for a given trait. It processes function arguments, extracts identifiers, and constructs a new struct that wraps the trait implementation in an Arc. This enables sharing the trait implementation across threads safely.

```rust
            .map(|arg| {
                if let syn::FnArg::Typed(pat_type) = arg {
                    if let syn::Pat::Ident(ident) = &*pat_type.pat {
                        &ident.ident
                    } else {
                        panic!("Unsupported parameter pattern");
                    }
                } else {
                    panic!("Unsupported parameter type");
                }
            })
            .collect::<Vec<_>>();

        let expanded = quote! {
            // Include the renamed trait (TraitImpl)
            #input

            /// Handle wrapper for the trait that provides Arc-based sharing
            #[derive(Clone)]
            pub struct #handle_name {
                inner: std::sync::Arc<dyn #impl_trait_name + Send + Sync>,
            }

            unsafe impl Send for #handle_name {}
            unsafe impl Sync for #handle_name {}

            impl #handle_name {
                /// Create a new handle from a trait implementation
                pub fn new(inner: impl #impl_trait_name + Send + Sync + 'static) -> Self {
                    Self {
                        inner: std::sync::Arc::new(inner),
                    }
                }

                /// Create a new handle from a boxed trait object
                pub fn from_boxed(inner: Box<dyn #impl_trait_name + Send + Sync>) -> Self {
                    Self {
                        inner: std::sync::Arc::from(inner),
                    }
                }
            }

            // Macro to generate methods for the handle
            macro_rules! impl_handle_method {
                ($method_name:ident($(#$arg:tt)*) -> $output:ty) => {
                    quote! {
                        pub fn #method_name(#inputs) #output {
                            self.inner.#method_name(#(#param_names),*)
                        }
                    }
                };
            }
        };
```

--------------------------------

### arc_handle Attribute Macro Usage

Source: https://docs.rs/arc-handle/latest/arc_handle/attr.arc_handle

Demonstrates how to use the `#[arc_handle]` attribute macro on an async trait to generate an Arc-based handle wrapper. This macro renames the original trait to `TraitImpl` and creates a handle struct with the original trait name, wrapping the trait in an `Arc<dyn TraitImpl + Send + Sync>`.

```rust
use arc_handle::arc_handle;
use async_trait::async_trait;

#[arc_handle]
#[async_trait]
pub trait MyTrait {
    async fn do_something(&self, value: i32) -> String;
    fn get_name(&self) -> &str;
}
```

--------------------------------

### arc_handle Attribute Macro Usage

Source: https://docs.rs/arc-handle/latest/src/arc_handle/lib.rs

Demonstrates how to use the `arc_handle` attribute macro to wrap a trait with an Arc-based handle. This macro renames the original trait to `TraitImpl` and creates a new struct with the original trait name that holds an `Arc<dyn TraitImpl + Send + Sync>`. It automatically generates methods on the handle that delegate to the inner trait implementation, making it easy to use traits across threads.

```rust
use arc_handle::arc_handle;
use async_trait::async_trait;

#[arc_handle]
#[async_trait]
pub trait MyTrait {
    async fn do_something(&self, value: i32) -> String;
    fn get_name(&self) -> &str;
}

```

--------------------------------

### arc_handle Attribute Macro

Source: https://docs.rs/arc-handle/latest/arc_handle/index

The `arc_handle` attribute macro generates an Arc-based handle wrapper for a given trait. This is useful for creating shared, mutable access to trait implementations across different parts of an application.

```rust
#[macro_use]
extern crate arc_handle;

#[arc_handle]
trait MyTrait {
    fn do_something(&self);
}

struct MyStruct;

impl MyTrait for MyStruct {
    fn do_something(&self) {
        println!("Doing something!");
    }
}

fn main() {
    let handle = MyTraitHandle::new(MyStruct);
    handle.do_something();
}
```

--------------------------------

### arc_handle Attribute Macro

Source: https://docs.rs/arc-handle/latest/arc_handle/all

The `arc_handle` attribute macro is used to generate Arc-based handle wrappers for traits. This allows for shared ownership and thread-safe access to trait objects.

```rust
#[proc_macro_derive(arc_handle)]
pub fn arc_handle_derive(input: TokenStream) -> TokenStream {
    // Implementation details for generating the Arc-based handle wrapper
    // ...
    input
}
```

--------------------------------

### arc_handle Attribute Macro

Source: https://docs.rs/arc-handle/latest/arc_handle

The `arc_handle` attribute macro generates an Arc-based handle wrapper for a given trait. This is useful for creating thread-safe, shared access to trait implementations.

```Rust
#[macro_use]
extern crate arc_handle;

use std::sync::Arc;

trait MyTrait {
    fn greet(&self);
}

struct MyStruct;

impl MyTrait for MyStruct {
    fn greet(&self) {
        println!("Hello from MyStruct!");
    }
}

#[arc_handle]
trait MyTraitHandle {
    fn greet(&self);
}

fn main() {
    let instance = Arc::new(MyStruct);
    let handle = MyTraitHandle::new(instance);
    handle.greet();
}
```

--------------------------------

### arc_handle Attribute Macro

Source: https://docs.rs/arc-handle/latest/index

The `arc_handle` attribute macro generates an Arc-based handle wrapper for a given trait. This is useful for creating thread-safe, shared access to trait implementations.

```Rust
#[macro_use]
extern crate arc_handle;

use std::sync::Arc;

trait MyTrait {
    fn greet(&self);
}

struct MyStruct;

impl MyTrait for MyStruct {
    fn greet(&self) {
        println!("Hello from MyStruct!");
    }
}

#[arc_handle]
trait MyTraitHandle {
    fn greet(&self);
}

fn main() {
    let instance = Arc::new(MyStruct);
    let handle = MyTraitHandle::new(instance);
    handle.greet();
}
```

--------------------------------

### Check if a Method is Asynchronous

Source: https://docs.rs/arc-handle/latest/src/arc_handle/lib.rs

This function checks if a given Rust method signature indicates an asynchronous operation. It relies on the `asyncness` field of the `Signature` struct.

```rust
fn is_async_method(sig: &Signature) -> bool {
    sig.asyncness.is_some()
}
```
Tokens:
Raw