Trait</th>	Primary Purpose</th>	Key Characteristics</th></tr></thead>
`AsRef</code></td>`	Cheap reference conversions</td>	- No guarantees about equality or hashing - Useful for generic functions accepting references</td></tr>
`Borrow</code></td>`	Borrowed data equivalence</td>	- Guarantees about equality and hashing - Essential for collections types like HashMap/BtreeMap</td></tr>
`Deref</code></td>`	Smart pointer functionality</td>	- Enables </code> operator - Enables deref coercion - Affects method resolution</td></tr> </tbody></table> Common Gotchas</a></h2> Deref Coercion Costs</strong></li> </ol> // Multiple deref coercions can have performance implications </span>let</span> s </span>= </span>Box</span>::</span>new(</span>String</span>::</span>from(</span>"hello"</span>))</span>; </span>takes_str</span>(</span>&</span>s)</span>; </span>// Box -> String -> str, two dereferences </span></code></pre> Borrow vs AsRef Choice</strong></li> </ol> // Wrong choice for HashMap key type </span>fn </span>bad_design</span><T</span>: </span>AsRef</span><</span>str</span>>>(</span>map</span>: </span>&</span>HashMap<T, </span>u32</span>>) {} </span>// Won't work well </span> </span>// Correct choice </span>fn </span>good_design</span><T</span>: </span>Borrow<</span>str</span>>>(</span>map</span>: </span>&</span>HashMap<T, </span>u32</span>>) {} </span></code></pre> Deref for Non-Pointer Types</strong></li> </ol> // Generally avoid implementing Deref for non-pointer-like types </span>// Could be confusing for other developers </span>struct </span>Seconds</span>(</span>u64</span>)</span>; </span>// Avoid this: </span>impl </span>Deref </span>for </span>Seconds </span>{ </span> </span>type </span>Target </span>= </span>u64</span>; </span> </span>fn </span>deref</span>(</span>&</span>self</span>) </span>-> </span>&</span>u64 </span>{ </span>&</span>self</span>.</span>0 </span>} </span>} </span></code></pre> Summary</a></h2> This overview covers the main differences and use cases for these three important Rust traits. The key is understanding their specific purposes and contracts to use them effectively in your code.</p> Understanding panic handling in larger codebase 2024-07-05T00:00:00+00:00 Comprehensive Guide to Panic Handling in Async Rust</a></h1> Introduction</a></h2> Panic handling in async Rust requires special consideration, especially in larger codebases where reliability and graceful error handling are crucial. This guide explores various aspects of panic handling, including best practices, common scenarios, and practical solutions.</p> Understanding Panics in Rust</a></h2> What is a Panic?</a></h3> fn </span>example_panic</span>() { </span> </span>panic!</span>(</span>"This is a panic!"</span>)</span>; </span>// Explicit panic </span> </span>let</span> v </span>= </span>vec!</span>[</span>1</span>, </span>2</span>, </span>3</span>]</span>; </span> v[</span>99</span>]</span>; </span>// Runtime panic: index out of bounds </span>} </span></code></pre> Common Panic Scenarios</a></h3> Array/Vector Index Out of Bounds</strong></li> </ol> fn </span>array_panic</span>() { </span> </span>let</span> arr </span>= </span>[</span>1</span>, </span>2</span>, </span>3</span>]</span>; </span> </span>let</span> index </span>= </span>5</span>; </span> </span>println!</span>(</span>"</span>{}</span>"</span>,</span> arr[index])</span>; </span>// PANIC! </span>} </span></code></pre> Integer Overflow in Debug Mode</strong></li> </ol> fn </span>overflow_panic</span>() { </span> </span>let</span> x</span>: </span>u8 </span>= </span>255</span>; </span> </span>let</span> y </span>=</span> x </span>+ </span>1</span>; </span>// PANIC in debug mode </span>} </span></code></pre> Unwrap on None</strong></li> </ol> fn </span>unwrap_panic</span>() { </span> </span>let</span> opt</span>: </span>Option</span><</span>i32</span>> </span>= </span>None</span>; </span> opt</span>.</span>unwrap</span>()</span>; </span>// PANIC! </span>} </span></code></pre> Panic Handling in Async Context</a></h2> The Challenge with Async Panics</a></h3> Async code introduces additional complexity because panics can occur in different contexts:</p> Task Panics</strong></li> </ol> async </span>fn </span>task_panic</span>() { </span> tokio</span>::</span>spawn(async { </span> </span>panic!</span>(</span>"Task panic!"</span>)</span>; </span> })</span>; </span>} </span></code></pre> Future Panics</strong></li> </ol> async </span>fn </span>future_panic</span>() </span>-> </span>Result</span><(), </span>Box</span><dyn std</span>::</span>error</span>::</span>Error>> { </span> </span>let</span> future </span>=</span> async { </span> </span>panic!</span>(</span>"Future panic!"</span>)</span>; </span> }</span>; </span> future</span>.</span>await </span>} </span></code></pre> Implementing Robust Panic Handling</a></h3> 1. Using catch_unwind in Async Context</a></h4> use </span>std</span>::</span>panic</span>::</span>{catch_unwind</span>,</span> AssertUnwindSafe}</span>; </span> </span>async </span>fn </span>handle_async_panic</span>() </span>-> </span>Result</span><(), </span>Box</span><dyn std</span>::</span>error</span>::</span>Error>> { </span> </span>let</span> result </span>= </span>catch_unwind</span>(AssertUnwindSafe(async { </span> </span>// Potentially panicking async code </span> </span>panic!</span>(</span>"Async panic!"</span>)</span>; </span> }))</span>.</span>await</span>; </span> </span> </span>match</span> result { </span> </span>Ok</span>(</span>_</span>) </span>=> </span>Ok</span>(())</span>, </span> </span>Err</span>(e) </span>=> </span>{ </span> </span>eprintln!</span>(</span>"Caught panic: </span>{:?}</span>"</span>,</span> e)</span>; </span> </span>Err</span>(</span>"Async operation panicked"</span>.</span>into</span>()) </span> } </span> } </span>} </span></code></pre> 2. Task-Level Panic Handling with Tokio</a></h4> use </span>tokio</span>::</span>task</span>::</span>JoinHandle</span>; </span> </span>async </span>fn </span>spawn_supervised_task</span>() </span>-> </span>Result</span><(), </span>Box</span><dyn std</span>::</span>error</span>::</span>Error>> { </span> </span>let</span> handle</span>: </span>JoinHandle<</span>Result</span><(), Error>> </span>= </span>tokio</span>::</span>spawn(async { </span> </span>// Your task code here </span> </span>Ok</span>(()) </span> })</span>; </span> </span> </span>match</span> handle</span>.</span>await { </span> </span>Ok</span>(</span>Ok</span>(</span>_</span>)) </span>=> </span>Ok</span>(())</span>, </span> </span>Ok</span>(</span>Err</span>(e)) </span>=> </span>Err</span>(e</span>.</span>into</span>())</span>, </span> </span>Err</span>(e) </span>if</span> e</span>.</span>is_panic</span>() </span>=> </span>{ </span> </span>eprintln!</span>(</span>"Task panicked: </span>{:?}</span>"</span>,</span> e)</span>; </span> </span>Err</span>(</span>"Task panic"</span>.</span>into</span>()) </span> } </span> </span>Err</span>(e) </span>=> </span>Err</span>(e</span>.</span>into</span>())</span>, </span> } </span>} </span></code></pre> Custom Panic Hooks for Application-Wide Handling</a></h3> use </span>std</span>::</span>panic</span>; </span>use </span>log</span>::</span>{error</span>,</span> info}</span>; </span> </span>fn </span>setup_panic_hooks</span>() { </span> panic</span>::</span>set_hook(</span>Box</span>::</span>new(\|</span>panic_info</span>\| { </span> </span>error!</span>(</span>"Application panic occurred!"</span>)</span>; </span> </span>error!</span>(</span>"Panic info: {:?}"</span>,</span> panic_info)</span>; </span> </span> </span>// Optional: Send panic info to monitoring service </span> </span>send_to_monitoring</span>(panic_info)</span>; </span> </span> </span>// Optional: Initiate graceful shutdown </span> </span>initiate_shutdown</span>()</span>; </span> }))</span>; </span>} </span> </span>fn </span>send_to_monitoring</span>(</span>panic_info</span>: </span>&</span>panic</span>::</span>PanicInfo) { </span> </span>// Implementation for sending to monitoring service </span>} </span> </span>fn </span>initiate_shutdown</span>() { </span> </span>// Implementation for graceful shutdown </span>} </span></code></pre> Structured Panic Handling for Large Applications</a></h2> 1. Panic Recovery Middleware</a></h3> use </span>std</span>::</span>future</span>::</span>Future</span>; </span>use </span>std</span>::</span>pin</span>::</span>Pin</span>; </span> </span>pub struct </span>PanicRecoveryMiddleware</span><S> { </span> inner</span>:</span> S, </span>} </span> </span>impl</span><S> </span>PanicRecoveryMiddleware</span><S> { </span> </span>pub fn </span>new</span>(</span>inner</span>:</span> S) </span>-> </span>Self </span>{ </span> </span>Self </span>{ inner } </span> } </span> </span> </span>pub</span> async </span>fn </span>handle_request</span><F, R>(</span>&</span>self</span>, </span>fut</span>:</span> F) </span>-> </span>Result</span><R, Error> </span> </span>where </span> F</span>: </span>Future<Output = R> + Send + </span>'static</span>, </span> R</span>:</span> Send + </span>'static</span>, </span> { </span> </span>let</span> result </span>= </span>tokio</span>::</span>spawn(async </span>move </span>{ </span> </span>catch_unwind</span>(AssertUnwindSafe(async </span>move </span>{ </span> fut</span>.</span>await </span> }))</span>.</span>await </span> })</span>.</span>await</span>??</span>; </span> </span> </span>Ok</span>(result) </span> } </span>} </span></code></pre> 2. Supervisor Pattern for Long-Running Tasks</a></h3> pub struct </span>TaskSupervisor </span>{ </span> tasks</span>: </span>Vec</span><JoinHandle<()>>, </span> shutdown_tx</span>: </span>broadcast</span>::</span>Sender<()>, </span>} </span> </span>impl </span>TaskSupervisor </span>{ </span> </span>pub fn </span>new</span>() </span>-> </span>Self </span>{ </span> </span>let </span>(shutdown_tx</span>, </span>_</span>) </span>= </span>broadcast</span>::</span>channel(</span>1</span>)</span>; </span> </span>Self </span>{ </span> tasks</span>: </span>Vec</span>::</span>new()</span>, </span> shutdown_tx</span>, </span> } </span> } </span> </span> </span>pub fn </span>spawn_supervised</span><F>(</span>&</span>mut </span>self</span>, </span>task</span>:</span> F) </span> </span>where </span> F</span>: </span>Future<Output = ()> + Send + </span>'static</span>, </span> { </span> </span>let mut</span> shutdown_rx </span>= </span>self</span>.</span>shutdown_tx</span>.</span>subscribe</span>()</span>; </span> </span> </span>let</span> handle </span>= </span>tokio</span>::</span>spawn(async </span>move </span>{ </span> tokio</span>::</span>select</span>! </span>{ </span> </span>_ =</span> shutdown_rx</span>.</span>recv</span>() </span>=> </span>{ </span> </span>info!</span>(</span>"Task received shutdown signal"</span>)</span>; </span> } </span> result </span>= </span>catch_unwind</span>(AssertUnwindSafe(task)) </span>=> </span>{ </span> </span>if let </span>Err</span>(e) </span>=</span> result { </span> </span>error!</span>(</span>"Task panicked: {:?}"</span>,</span> e)</span>; </span> } </span> } </span> } </span> })</span>; </span> </span> </span>self</span>.</span>tasks</span>.</span>push</span>(handle)</span>; </span> } </span> </span> </span>pub</span> async </span>fn </span>shutdown</span>(</span>self</span>) { </span> </span>let </span>_ = </span>self</span>.</span>shutdown_tx</span>.</span>send</span>(())</span>; </span> </span> </span>for</span> task </span>in </span>self</span>.</span>tasks { </span> </span>if let </span>Err</span>(e) </span>=</span> task</span>.</span>await { </span> </span>error!</span>(</span>"Error shutting down task: {:?}"</span>,</span> e)</span>; </span> } </span> } </span> } </span>} </span></code></pre> 3. Error Context and Reporting</a></h3> #</span>[</span>derive</span>(Debug)] </span>pub struct </span>PanicContext </span>{ </span> </span>pub </span>timestamp</span>: </span>DateTime<Utc>, </span> </span>pub </span>thread</span>:</span> String, </span> </span>pub </span>backtrace</span>:</span> Backtrace, </span> </span>pub </span>message</span>:</span> String, </span>} </span> </span>impl </span>PanicContext </span>{ </span> </span>pub fn </span>capture</span>(</span>panic_info</span>: </span>&</span>panic</span>::</span>PanicInfo) </span>-> </span>Self </span>{ </span> </span>Self </span>{ </span> timestamp</span>: </span>Utc</span>::</span>now()</span>, </span> thread</span>: </span>thread</span>::</span>current()</span>.</span>name</span>() </span> </span>.</span>unwrap_or</span>(</span>"unnamed"</span>) </span> </span>.</span>to_string</span>()</span>, </span> backtrace</span>: </span>Backtrace</span>::</span>capture()</span>, </span> message</span>:</span> panic_info</span>.</span>to_string</span>()</span>, </span> } </span> } </span> </span> </span>pub</span> async </span>fn </span>report</span>(</span>&</span>self</span>) { </span> </span>// Implementation for reporting panic context </span> </span>// Could send to logging service, monitoring system, etc. </span> } </span>} </span></code></pre> Best Practices for Panic Prevention</a></h2> 1. Defensive Programming</a></h3> fn </span>defensive_array_access</span>(</span>arr</span>: </span>&</span>[</span>i32</span>], </span>index</span>: </span>usize</span>) </span>-> </span>Option</span><</span>i32</span>> { </span> arr</span>.</span>get</span>(index)</span>.</span>copied</span>() </span>} </span> </span>async </span>fn </span>process_data</span>(</span>data</span>: </span>&</span>[</span>i32</span>]) </span>-> </span>Result</span><(), Error> { </span> </span>for</span> i </span>in </span>0</span>..</span>data</span>.</span>len</span>() { </span> </span>if let </span>Some</span>(value) </span>= </span>defensive_array_access</span>(data</span>,</span> i) { </span> </span>process_value</span>(value)</span>.</span>await</span>?</span>; </span> } </span> } </span> </span>Ok</span>(()) </span>} </span></code></pre> 2. Resource Cleanup with Drop</a></h3> struct </span>DatabaseConnection </span>{ </span> client</span>:</span> Client, </span>} </span> </span>impl </span>Drop </span>for </span>DatabaseConnection </span>{ </span> </span>fn </span>drop</span>(</span>&</span>mut </span>self</span>) { </span> </span>// Ensure resources are cleaned up even in case of panic </span> </span>if let </span>Err</span>(e) </span>= </span>self</span>.</span>client</span>.</span>close</span>() { </span> </span>error!</span>(</span>"Error closing database connection: {:?}"</span>,</span> e)</span>; </span> } </span> } </span>} </span></code></pre> 3. Structured Logging for Better Debugging</a></h3> use </span>tracing</span>::</span>{info</span>,</span> error</span>,</span> instrument}</span>; </span> </span>#</span>[</span>instrument</span>] </span>async </span>fn </span>critical_operation</span>() </span>-> </span>Result</span><(), Error> { </span> </span>info!</span>(</span>"Starting critical operation"</span>)</span>; </span> </span> </span>if let </span>Err</span>(e) </span>= </span>perform_operation</span>()</span>.</span>await { </span> </span>error!</span>(error </span>= ?</span>e</span>, </span>"Critical operation failed"</span>)</span>; </span> </span>return </span>Err</span>(e)</span>; </span> } </span> </span> </span>info!</span>(</span>"Critical operation completed successfully"</span>)</span>; </span> </span>Ok</span>(()) </span>} </span></code></pre> Testing Panic Handling</a></h2> 1. Unit Tests for Panic Recovery</a></h3> #</span>[</span>cfg</span>(test)] </span>mod </span>tests </span>{ </span> </span>use super</span>::</span>; </span> </span> </span>#</span>[</span>tokio</span>::</span>test</span>] </span> async </span>fn </span>test_panic_recovery</span>() { </span> </span>let</span> result </span>= </span>catch_unwind</span>(AssertUnwindSafe(async { </span> </span>panic!</span>(</span>"Test panic"</span>)</span>; </span> }))</span>.</span>await</span>; </span> </span> </span>assert!</span>(result</span>.</span>is_err</span>())</span>; </span> } </span>} </span></code></pre> 2. Integration Tests</a></h3> #</span>[</span>tokio</span>::</span>test</span>] </span>async </span>fn </span>test_supervisor_recovery</span>() { </span> </span>let mut</span> supervisor </span>= </span>TaskSupervisor</span>::</span>new()</span>; </span> </span> supervisor</span>.</span>spawn_supervised</span>(async { </span> </span>panic!</span>(</span>"Supervised task panic"</span>)</span>; </span> })</span>; </span> </span> </span>// Wait for some time </span> tokio</span>::</span>time</span>::</span>sleep(Duration</span>::</span>from_secs(</span>1</span>))</span>.</span>await</span>; </span> </span> </span>// Verify supervisor state </span> supervisor</span>.</span>shutdown</span>()</span>.</span>await</span>; </span>} </span></code></pre> Production Considerations</a></h2> 1. Memory Safety in Panic Situations</a></h3> struct </span>SafeResource</span><T> { </span> inner</span>: </span>Option</span><T>, </span>} </span> </span>impl</span><T> </span>SafeResource</span><T> { </span> </span>pub fn </span>new</span>(</span>resource</span>:</span> T) </span>-> </span>Self </span>{ </span> </span>Self </span>{ </span> inner</span>: </span>Some</span>(resource) </span> } </span> } </span> </span> </span>pub</span> async </span>fn </span>use_resource</span><F, R>(</span>&</span>mut </span>self</span>, </span>f</span>:</span> F) </span>-> </span>Result</span><R, Error> </span> </span>where </span> F</span>:</span> FnOnce(</span>&</span>mut</span> T) -> R, </span> { </span> </span>let</span> resource </span>= </span>self</span>.</span>inner</span>.</span>as_mut</span>() </span> </span>.</span>ok_or_else</span>(\|\| Error</span>::</span>ResourceUnavailable)</span>?</span>; </span> </span> </span>Ok</span>(</span>f</span>(resource)) </span> } </span>} </span> </span>impl</span><T> Drop </span>for </span>SafeResource</span><T> { </span> </span>fn </span>drop</span>(</span>&</span>mut </span>self</span>) { </span> </span>if let </span>Some</span>(resource) </span>= </span>self</span>.</span>inner</span>.</span>take</span>() { </span> </span>// Clean up resource </span> } </span> } </span>} </span></code></pre> 2. Monitoring and Alerting</a></h3> async </span>fn </span>monitor_task_health</span>( </span> </span>task_metrics</span>: </span>Arc<TaskMetrics>, </span> </span>alert_client</span>:</span> AlertClient, </span>) { </span> </span>loop </span>{ </span> </span>if</span> task_metrics</span>.</span>panic_count</span>.</span>load</span>(Ordering</span>::</span>Relaxed) </span>> </span>0 </span>{ </span> alert_client</span>.</span>send_alert</span>( </span> AlertLevel</span>::</span>Critical</span>, </span> </span>"Task panic detected"</span>, </span> )</span>.</span>await</span>; </span> } </span> </span> tokio</span>::</span>time</span>::</span>sleep(Duration</span>::</span>from_secs(</span>60</span>))</span>.</span>await</span>; </span> } </span>} </span></code></pre> 3. Graceful Shutdown Implementation</a></h3> pub struct </span>Application </span>{ </span> supervisor</span>:</span> TaskSupervisor, </span> shutdown_signal</span>: </span>broadcast</span>::</span>Receiver<()>, </span>} </span> </span>impl </span>Application </span>{ </span> </span>pub</span> async </span>fn </span>run</span>(</span>mut </span>self</span>) </span>-> </span>Result</span><(), Error> { </span> </span>loop </span>{ </span> tokio</span>::</span>select</span>! </span>{ </span> </span>_ = </span>self</span>.</span>shutdown_signal</span>.</span>recv</span>() </span>=> </span>{ </span> </span>info!</span>(</span>"Shutdown signal received"</span>)</span>; </span> </span>break</span>; </span> } </span> err </span>= </span>self</span>.</span>supervisor</span>.</span>check_tasks</span>() </span>=> </span>{ </span> </span>if let </span>Err</span>(e) </span>=</span> err { </span> </span>error!</span>(</span>"Task error: {:?}"</span>,</span> e)</span>; </span> </span>break</span>; </span> } </span> } </span> } </span> } </span> </span> </span>self</span>.</span>supervisor</span>.</span>shutdown</span>()</span>.</span>await</span>; </span> </span>Ok</span>(()) </span> } </span>} </span></code></pre> Conclusion</a></h2> Proper panic handling in async Rust requires:</p> Understanding different panic scenarios</li> Implementing appropriate recovery mechanisms</li> Using supervisor patterns for task management</li> Ensuring proper resource cleanup</li> Implementing monitoring and alerting</li> Testing panic handling thoroughly</li> Following best practices for prevention</li> </ol> Remember that while panic handling is important, it's better to design your code to avoid panics where possible, using Result and Option types for expected error cases.</p> Send and Sync hazard 2024-07-04T00:00:00+00:00 Understanding Send and Sync Hazards in Rust: A Comprehensive Guide</a></h1> Introduction</a></h2> The Send</code> and Sync</code> traits play a crucial role in Rust's concurrency safety model. However, incorrect implementations or assumptions about these traits can lead to serious bugs and undefined behavior, especially in large async codebases.</p> Foundation: Understanding Send and Sync</a></h2> pub unsafe</span> auto </span>trait </span>Send </span>{} </span>pub unsafe</span> auto </span>trait </span>Sync </span>{} </span></code></pre> Basic Definitions</a></h3> // Send: Type can be safely transferred across thread boundaries </span>trait </span>Send </span>{} </span> </span>// Sync: Type can be safely shared across thread boundaries </span>trait </span>Sync </span>{} </span> </span>// Relationship: T: Sync implies &T: Send </span></code></pre> Common Hazards and Anti-patterns</a></h2> 1. Incorrect Manual Implementation of Send/Sync</a></h3> // DANGEROUS: Incorrect implementation </span>struct </span>UnsafeCounter </span>{ </span> count</span>: </span>mut i32</span>, </span>} </span> </span>// THIS IS UNSAFE AND INCORRECT </span>unsafe impl </span>Send </span>for </span>UnsafeCounter </span>{} </span>// WRONG! </span>unsafe impl </span>Sync </span>for </span>UnsafeCounter </span>{} </span>// WRONG! </span> </span>// The correct way would be: </span>struct </span>SafeCounter </span>{ </span> count</span>: </span>Arc<AtomicI32>, </span>} </span>// This automatically implements Send and Sync safely </span></code></pre> 2. Interior Mutability Hazards</a></h3> use </span>std</span>::</span>cell</span>::</span>Cell</span>; </span>use </span>std</span>::</span>sync</span>::</span>Arc</span>; </span> </span>// DANGEROUS: Cell is !Sync but wrapped in Arc </span>struct </span>SharedState </span>{ </span> value</span>: </span>Arc<Cell<</span>i32</span>>>, </span>// This is a trap! </span>} </span> </span>impl </span>SharedState </span>{ </span> </span>pub fn </span>increment</span>(</span>&</span>self</span>) { </span> </span>// This is undefined behavior when shared across threads </span> </span>self</span>.</span>value</span>.</span>set</span>(</span>self</span>.</span>value</span>.</span>get</span>() </span>+ </span>1</span>)</span>; </span> } </span>} </span> </span>// SAFE: Using proper atomic types </span>struct </span>SafeSharedState </span>{ </span> value</span>: </span>Arc<AtomicI32>, </span>} </span> </span>impl </span>SafeSharedState </span>{ </span> </span>pub fn </span>increment</span>(</span>&</span>self</span>) { </span> </span>self</span>.</span>value</span>.</span>fetch_add</span>(</span>1</span>, </span>Ordering</span>::</span>SeqCst)</span>; </span> } </span>} </span></code></pre> 3. Async Context Hazards</a></h3> // DANGEROUS: Mixing async and sync code incorrectly </span>struct </span>AsyncProcessor </span>{ </span> data</span>: </span>Arc<Mutex<</span>Vec</span><</span>String</span>>>>, </span>} </span> </span>impl </span>AsyncProcessor </span>{ </span> </span>// HAZARD: Blocking in async context </span> async </span>fn </span>process</span>(</span>&</span>self</span>) </span>-> </span>Result</span><(), </span>Box</span><dyn Error>> { </span> </span>let mut</span> data </span>= </span>self</span>.</span>data</span>.</span>lock</span>()</span>.</span>unwrap</span>()</span>; </span>// Could block! </span> </span>// Process data </span> </span>Ok</span>(()) </span> } </span>} </span> </span>// SAFE: Using async-aware primitives </span>struct </span>SafeAsyncProcessor </span>{ </span> data</span>: </span>Arc<</span>Tokio</span>::</span>sync</span>::</span>Mutex<</span>Vec</span><</span>String</span>>>>, </span>} </span> </span>impl </span>SafeAsyncProcessor </span>{ </span> async </span>fn </span>process</span>(</span>&</span>self</span>) </span>-> </span>Result</span><(), </span>Box</span><dyn Error>> { </span> </span>let mut</span> data </span>= </span>self</span>.</span>data</span>.</span>lock</span>()</span>.</span>await</span>; </span> </span>// Process data </span> </span>Ok</span>(()) </span> } </span>} </span></code></pre> Complex Hazards in Large Systems</a></h2> 1. Hidden Sync Requirements</a></h3> struct </span>ComplexSystem </span>{ </span> cache</span>: </span>Arc<Cache>, </span> processor</span>: </span>Arc<DataProcessor>, </span> notifier</span>: </span>Arc<EventNotifier>, </span>} </span> </span>// DANGEROUS: Hidden non-Send type </span>struct </span>Cache </span>{ </span> entries</span>: </span>HashMap<</span>String</span>, Rc<CacheEntry>>, </span>// Rc is !Send </span> _phantom</span>: </span>PhantomData<</span>const </span>()>, </span>// !Send and !Sync </span>} </span> </span>// SAFE: Explicit Send/Sync bounds </span>struct </span>SafeCache </span>{ </span> entries</span>: </span>Arc<DashMap<</span>String</span>, Arc<CacheEntry>>>, </span>} </span></code></pre> 2. Callback Hell with Send/Sync Issues</a></h3> // DANGEROUS: Callbacks with unclear Send/Sync requirements </span>struct </span>EventSystem </span>{ </span> callbacks</span>: </span>Vec</span><</span>Box</span><dyn </span>Fn</span>() </span>+ </span>Send </span>+ </span>'static</span>>>, </span> unsafe_callbacks</span>: </span>Vec</span><</span>Box</span><dyn </span>Fn</span>()>>, </span>// Missing Send bound! </span>} </span> </span>// SAFE: Explicit bounds and type-safe callbacks </span>struct </span>SafeEventSystem</span><F> </span>where </span> F: Fn() </span>+ </span>Send </span>+ </span>Sync </span>+ </span>'static</span>, </span>{ </span> callbacks</span>: </span>Vec</span><F></span>, </span>} </span></code></pre> 3. Resource Management Hazards</a></h3> // DANGEROUS: Resource cleanup with Send/Sync issues </span>struct </span>ResourceManager </span>{ </span> resources</span>: </span>Arc<Mutex<</span>Vec</span><Resource>>>, </span> cleanup_callbacks</span>: </span>Vec</span><</span>Box</span><dyn </span>FnMut</span>() </span>+ </span>Send</span>>>, </span>} </span> </span>impl </span>ResourceManager </span>{ </span> </span>// HAZARD: Cleanup in destructor could panic or deadlock </span> </span>fn </span>cleanup</span>(</span>&</span>mut </span>self</span>) { </span> </span>let</span> resources </span>= </span>self</span>.</span>resources</span>.</span>lock</span>()</span>.</span>unwrap</span>()</span>; </span> </span>for</span> callback </span>in &</span>mut </span>self</span>.</span>cleanup_callbacks { </span> </span>callback</span>()</span>; </span>// Could panic or deadlock! </span> } </span> } </span>} </span> </span>// SAFE: Structured resource management </span>struct </span>SafeResourceManager </span>{ </span> resources</span>: </span>Arc<</span>Tokio</span>::</span>sync</span>::</span>Mutex<</span>Vec</span><Resource>>>, </span> cleanup_callbacks</span>: </span>Arc<</span>Tokio</span>::</span>sync</span>::</span>Mutex<</span>Vec</span><</span>Box</span><dyn </span>FnMut</span>() </span>+ </span>Send </span>+ </span>Sync</span>>>>>, </span>} </span> </span>impl </span>SafeResourceManager </span>{ </span> async </span>fn </span>cleanup</span>(</span>&</span>mut </span>self</span>) { </span> </span>let mut</span> resources </span>= </span>self</span>.</span>resources</span>.</span>lock</span>()</span>.</span>await</span>; </span> </span>let mut</span> callbacks </span>= </span>self</span>.</span>cleanup_callbacks</span>.</span>lock</span>()</span>.</span>await</span>; </span> </span> </span>for</span> callback </span>in</span> callbacks</span>.</span>iter_mut</span>() { </span> </span>// Handle cleanup errors gracefully </span> </span>if let </span>Err</span>(e) </span>= </span>std</span>::</span>panic</span>::</span>catch_unwind(std</span>::</span>panic</span>::</span>AssertUnwindSafe(\|\| { </span> </span>callback</span>()</span>; </span> })) { </span> log</span>::</span>error</span>!</span>(</span>"Cleanup callback panicked: {:?}"</span>,</span> e)</span>; </span> } </span> } </span> } </span>} </span></code></pre> Thread Pool and Executor Hazards</a></h2> 1. Executor State Sharing</a></h3> // DANGEROUS: Incorrect executor state sharing </span>struct </span>AsyncExecutor </span>{ </span> state</span>: </span>Arc<Mutex<ExecutorState>>, </span> runtime</span>: </span>tokio</span>::</span>runtime</span>::</span>Runtime, </span>} </span> </span>struct </span>ExecutorState </span>{ </span> tasks</span>: </span>Vec</span><</span>Box</span><dyn Future<Output = ()> </span>+ </span>Send</span>>>, </span> callbacks</span>: </span>Vec</span><</span>Box</span><dyn </span>Fn</span>() </span>+ </span>Send</span>>>, </span>} </span> </span>// HAZARD: Could deadlock or cause undefined behavior </span>impl </span>AsyncExecutor </span>{ </span> async </span>fn </span>execute</span>(</span>&</span>self</span>) { </span> </span>let</span> state </span>= </span>self</span>.</span>state</span>.</span>lock</span>()</span>.</span>unwrap</span>()</span>; </span> </span>for</span> task </span>in &</span>state</span>.</span>tasks { </span> </span>self</span>.</span>runtime</span>.</span>spawn</span>(task)</span>; </span>// Could deadlock! </span> } </span> } </span>} </span> </span>// SAFE: Proper async-aware state management </span>struct </span>SafeAsyncExecutor </span>{ </span> state</span>: </span>Arc<</span>Tokio</span>::</span>sync</span>::</span>Mutex<ExecutorState>>, </span> runtime</span>: </span>tokio</span>::</span>runtime</span>::</span>Runtime, </span>} </span> </span>impl </span>SafeAsyncExecutor </span>{ </span> async </span>fn </span>execute</span>(</span>&</span>self</span>) { </span> </span>let mut</span> state </span>= </span>self</span>.</span>state</span>.</span>lock</span>()</span>.</span>await</span>; </span> </span>for</span> task </span>in</span> state</span>.</span>tasks</span>.</span>drain</span>(</span>..</span>) { </span> </span>self</span>.</span>runtime</span>.</span>spawn</span>(task)</span>; </span> } </span> } </span>} </span></code></pre> 2. Task Cancellation Hazards</a></h3> // DANGEROUS: Incorrect task cancellation </span>struct </span>TaskManager </span>{ </span> tasks</span>: </span>Arc<Mutex<HashMap<TaskId, JoinHandle<()>>>>, </span>} </span> </span>impl </span>TaskManager </span>{ </span> </span>// HAZARD: Deadlock potential during cleanup </span> </span>fn </span>cancel_all</span>(</span>&</span>self</span>) { </span> </span>let</span> tasks </span>= </span>self</span>.</span>tasks</span>.</span>lock</span>()</span>.</span>unwrap</span>()</span>; </span> </span>for </span>(</span>_</span>,</span> handle) </span>in</span> tasks</span>.</span>iter</span>() { </span> handle</span>.</span>abort</span>()</span>; </span>// Could deadlock if task holds locks! </span> } </span> } </span>} </span> </span>// SAFE: Graceful task cancellation </span>struct </span>SafeTaskManager </span>{ </span> tasks</span>: </span>Arc<</span>Tokio</span>::</span>sync</span>::</span>Mutex<HashMap<TaskId, JoinHandle<()>>>>, </span> shutdown_signal</span>: </span>broadcast</span>::</span>Sender<()>, </span>} </span> </span>impl </span>SafeTaskManager </span>{ </span> async </span>fn </span>cancel_all</span>(</span>&</span>self</span>) { </span> </span>// Signal all tasks to shut down </span> </span>let </span>_ = </span>self</span>.</span>shutdown_signal</span>.</span>send</span>(())</span>; </span> </span> </span>// Wait for tasks with timeout </span> </span>let mut</span> tasks </span>= </span>self</span>.</span>tasks</span>.</span>lock</span>()</span>.</span>await</span>; </span> </span>for </span>(</span>_</span>,</span> handle) </span>in</span> tasks</span>.</span>drain</span>() { </span> tokio</span>::</span>select</span>! </span>{ </span> </span>_ =</span> handle </span>=> </span>{}</span>, </span> </span>_ = </span>tokio</span>::</span>time</span>::</span>sleep(Duration</span>::</span>from_secs(</span>5</span>)) </span>=> </span>{ </span> handle</span>.</span>abort</span>()</span>; </span> } </span> } </span> } </span> } </span>} </span></code></pre> Best Practices and Mitigation Strategies</a></h2> 1. Type-Level Safety Guards</a></h3> use </span>std</span>::</span>marker</span>::</span>PhantomData</span>; </span> </span>// Enforce Send/Sync at type level </span>struct </span>ThreadSafeWrapper</span><T</span>: </span>Send </span>+ </span>Sync</span>> { </span> inner</span>:</span> T, </span> _marker</span>: </span>PhantomData<</span>const </span>()>, </span>} </span> </span>impl</span><T</span>: </span>Send </span>+ </span>Sync</span>> </span>ThreadSafeWrapper</span><T> { </span> </span>fn </span>new</span>(</span>inner</span>:</span> T) </span>-> </span>Self </span>{ </span> </span>Self </span>{ </span> inner</span>, </span> _marker</span>:</span> PhantomData</span>, </span> } </span> } </span>} </span></code></pre> 2. Compile-Time Verification</a></h3> #</span>[</span>cfg</span>(test)] </span>mod </span>tests </span>{ </span> </span>use </span>static_assertions</span>::</span>{assert_impl_all</span>,</span> assert_not_impl_any}</span>; </span> </span> </span>// Verify type safety at compile time </span> </span>assert_impl_all!</span>(SafeType</span>: </span>Send</span>, </span>Sync</span>)</span>; </span> </span>assert_not_impl_any!</span>(UnsafeType</span>: </span>Send</span>, </span>Sync</span>)</span>; </span>} </span></code></pre> 3. Runtime Checks</a></h3> use </span>std</span>::</span>any</span>::</span>Any</span>; </span> </span>fn </span>verify_send_sync</span><T</span>: </span>Send </span>+ </span>Sync </span>+</span> Any>() { </span> </span>println!</span>(</span>"Type </span>{}</span> is Send + Sync"</span>, </span>std</span>::</span>any</span>::</span>type_name</span>::</span><T>())</span>; </span>} </span> </span>#</span>[</span>test</span>] </span>fn </span>verify_types</span>() { </span> verify_send_sync</span>::</span><SafeType>()</span>; </span> </span>// verify_send_sync::<UnsafeType>(); // Won't compile </span>} </span></code></pre> Debugging and Analyzing Send/Sync Issues</a></h2> 1. Static Analysis Tools</a></h3> #</span>[</span>derive</span>(Debug)] </span>struct </span>DataStructure </span>{ </span> </span>#</span>[</span>allow</span>(dead_code)] </span> data</span>: </span>Vec</span><</span>String</span>>, </span>} </span> </span>// Use clippy to catch potential issues </span>#</span>[</span>warn</span>(clippy::missing_safety_doc)] </span>unsafe impl </span>Send </span>for </span>DataStructure </span>{} </span>// Clippy will warn about missing safety documentation </span></code></pre> 2. Runtime Diagnostics</a></h3> use </span>tracing</span>::</span>{info</span>,</span> error</span>,</span> warn}</span>; </span> </span>async </span>fn </span>monitor_thread_safety</span><T</span>: </span>Send </span>+ </span>Sync</span>>(</span>value</span>:</span> T) { </span> </span>let</span> type_name </span>= </span>std</span>::</span>any</span>::</span>type_name</span>::</span><T>()</span>; </span> </span> </span>info!</span>(</span>"Monitoring thread safety for type: {}"</span>,</span> type_name)</span>; </span> </span> </span>if </span>std</span>::</span>mem</span>::</span>size_of</span>::</span><T>() </span>> </span>512 </span>{ </span> </span>warn!</span>(</span>"Large type may cause performance issues when sent between threads"</span>)</span>; </span> } </span> </span> </span>// Monitor for potential issues </span> tokio</span>::</span>spawn(async </span>move </span>{ </span> </span>if let </span>Err</span>(e) </span>= </span>process_value</span>(value)</span>.</span>await { </span> </span>error!</span>(</span>"Thread safety violation: {:?}"</span>,</span> e)</span>; </span> } </span> })</span>; </span>} </span></code></pre> Conclusion</a></h2> When working with Send and Sync traits in large async Rust codebases:</p> Always Consider Thread Safety</strong></p> Verify Send/Sync implementations</li> Use appropriate synchronization primitives</li> Consider async-aware alternatives</li> </ul> </li> Design for Safety</strong></p> Use type-level guarantees</li> Implement proper resource cleanup</li> Handle task cancellation gracefully</li> </ul> </li> Monitor and Debug</strong></p> Use static analysis tools</li> Implement runtime diagnostics</li> Test thoroughly for concurrency issues</li> </ul> </li> Follow Best Practices</strong></p> Use async-aware primitives</li> Implement proper error handling</li> Consider performance implications</li> </ul> </li> Documentation</strong></p> Document thread safety requirements</li> Explain synchronization strategies</li> Detail potential hazards</li> </ul> </li> </ol> Remember that incorrect Send/Sync implementations can lead to subtle and dangerous bugs. Always err on the side of caution and thoroughly test concurrent code.</p> Understanding stream in rust 2024-07-03T00:00:00+00:00 Comprehensive Guide to Futures::Stream in Rust</a></h1> Introduction</a></h2> futures::Str </span> </span> </span> </span> </span> </span>} </span></code></pre> </span> </span>} </span> </span> </span> </span> </span>} </span></code></pre> </span> </span> </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> } </span>} </span></code></pre> </span> </span> </span> </span>} </span> </span> </span> </span> </span> </span> </span> } </span> } </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> } </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> } </span>} </span></code></pre> </span> </span> </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> } </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> </span> } </span> </span> } </span> } </span>} </span></code></pre> </span> </span> </span> </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> } </span> </span> </span> </span> </span> </span> } </span> </span> } </span> } </span>} </span></code></pre> </span> </span> </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> } </span> </span> </span> } </span> } </span> </span> </span> </span> </span> )) </span> </span> </span> } </span> } </span>} </span></code></pre> </span> </span> </span>} </span> </span> </span> </span> </span> </span>{ </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> }))) </span> } </span> </span> </span> } </span> } </span>} </span></code></pre> </span> </span> </span>} </span> </span> </span> </span>{ </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> } </span> </span> } </span> </span> } </span> } </span> } </span>} </span></code></pre> </span> </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> } </span> } </span>} </span></code></pre> </span> </span> </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> } </span> } </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span>} </span></code></pre> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> } </span>} </span></code></pre> </span> </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> </span> } </span> </span> } </span> } </span>} </span></code></pre> </span> </span> </span>} </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> } </span> </span> </span> </span> </span> </span> </span> } </span> </span> } </span> } </span> } </span> </span> </span> </span> )) </span> } </span>} </span></code></pre> Asynchronous Natural Efficient Support for back-pressure</li> </ul> </li> Composa Easy Rich set of combinators</li> Integration </ul> </li> Memory Lazy evaluation</li> Controlled buffering</li> Stream </ul> </li> </ol> Complex More Pin requirements</li> Error handling complexity</li> </ul> </li> Runtime Task scheduling overhead</li> Memory Context switching costs</li> </ul> </li> Learning Understanding Dealing with lifetimes</li> Managing pinning</li> </ul> </li> </ol> futures:: Efficient Rich Good </ul> However, Implementation complexity</li> Memory management</li> Error handling strategies</li> Performance implications</li> </ul> The key Remember to:</p> Profile Test Consider Handle Optimize </ul> This comprehensive Don't block just flow 2024-03-02T00:00:00+00:00 eam</code> is a fundamental abstraction in asynchronous Rust programming that represents a sequence of asynchronous values. This guide explores its design, implementation patterns, and practical considerations.</p> class="zola-anchor" href="#basic-concepts" aria-label="Anchor link for: basic-concepts">Basic Concepts</a></h2> it-definition">Stream Trait Definition</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">pub trait </span>Stream </span>{ </span>type </span>Item</span>; </span>fn </span>poll_next</span>( </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>></span>; ences-from-iterator">Key Differences from Iterator</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">// Iterator (synchronous) style="color:#fa6e32;">trait </span>Iterator </span>{ </span>type </span>Item</span>; </span>fn </span>next</span>(</span>&</span>mut </span>self</span>) </span>-> </span>Option</span><</span>Self</span>::</span>Item></span>; style="font-style:italic;color:#abb0b6;">// Stream (asynchronous) style="color:#fa6e32;">trait </span>Stream </span>{ </span>type </span>Item</span>; </span>fn </span>poll_next</span>(</span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>>) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>></span>; tion-patterns">Implementation Patterns</a></h2> ream-implementation">1. Basic Stream Implementation</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">use </span>futures</span>::</span>{Stream</span>,</span> StreamExt}</span>; style="color:#fa6e32;">use </span>std</span>::</span>pin</span>::</span>Pin</span>; style="color:#fa6e32;">use </span>std</span>::</span>task</span>::</span>{Context</span>,</span> Poll}</span>; style="color:#fa6e32;">struct </span>CounterStream </span>{ current</span>: </span>u64</span>, max</span>: </span>u64</span>, style="color:#fa6e32;">impl </span>Stream </span>for </span>CounterStream </span>{ </span>type </span>Item </span>= </span>u64</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>_cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>if </span>self</span>.</span>current </span>>= </span>self</span>.</span>max { </span>return </span>Poll</span>::</span>Ready(</span>None</span>)</span>; </span>let</span> result </span>= </span>self</span>.</span>current</span>; </span>self</span>.</span>current </span>+= </span>1</span>; Poll</span>::</span>Ready(</span>Some</span>(result)) -stream-implementation">2. Buffered Stream Implementation</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">use </span>std</span>::</span>collections</span>::</span>VecDeque</span>; style="color:#fa6e32;">struct </span>BufferedStream</span><T> { buffer</span>: </span>VecDeque<T>, source</span>: </span>Box</span><dyn Stream<Item = T> </span>+</span> Unpin>, capacity</span>: </span>usize</span>, style="color:#fa6e32;">impl</span><T> </span>BufferedStream</span><T> { </span>fn </span>new</span>(</span>source</span>:</span> impl Stream<Item = T> + Unpin + </span>'static</span>, </span>capacity</span>: </span>usize</span>) </span>-> </span>Self </span>{ </span>Self </span>{ buffer</span>: </span>VecDeque</span>::</span>with_capacity(capacity)</span>, source</span>: </span>Box</span>::</span>new(source)</span>, capacity</span>, style="color:#fa6e32;">impl</span><T> Stream </span>for </span>BufferedStream</span><T> { </span>type </span>Item </span>=</span> T</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>// Try to fill buffer </span>while </span>self</span>.</span>buffer</span>.</span>len</span>() </span>< </span>self</span>.</span>capacity { </span>match </span>Pin</span>::</span>new(</span>&</span>mut </span>self</span>.</span>source)</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(item)) </span>=> </span>self</span>.</span>buffer</span>.</span>push_back</span>(item)</span>, Poll</span>::</span>Ready(</span>None</span>) </span>=> </span>break</span>, Poll</span>::</span>Pending </span>=> </span>break</span>, </span>// Return item from buffer if available </span>if let </span>Some</span>(item) </span>= </span>self</span>.</span>buffer</span>.</span>pop_front</span>() { Poll</span>::</span>Ready(</span>Some</span>(item)) } </span>else if </span>self</span>.</span>buffer</span>.</span>is_empty</span>() { Pin</span>::</span>new(</span>&</span>mut </span>self</span>.</span>source)</span>.</span>poll_next</span>(cx) } </span>else </span>{ Poll</span>::</span>Pending tream-patterns">Advanced Stream Patterns</a></h2> ssure-implementation">1. Back-Pressure Implementation</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct </span>BackPressuredStream</span><T> { inner</span>: </span>Pin<</span>Box</span><dyn Stream<Item = T>>>, high_watermark</span>: </span>usize</span>, current_pressure</span>: </span>usize</span>, style="color:#fa6e32;">impl</span><T> </span>BackPressuredStream</span><T> { </span>fn </span>new</span>( </span>inner</span>:</span> impl Stream<Item = T> + </span>'static</span>, </span>high_watermark</span>: </span>usize ) </span>-> </span>Self </span>{ </span>Self </span>{ inner</span>: </span>Box</span>::</span>pin(inner)</span>, high_watermark</span>, current_pressure</span>: </span>0</span>, style="color:#fa6e32;">impl</span><T> Stream </span>for </span>BackPressuredStream</span><T> { </span>type </span>Item </span>=</span> T</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>if </span>self</span>.</span>current_pressure </span>>= </span>self</span>.</span>high_watermark { </span>return </span>Poll</span>::</span>Pending</span>; </span>match </span>self</span>.</span>inner</span>.</span>as_mut</span>()</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(item)) </span>=> </span>{ </span>self</span>.</span>current_pressure </span>+= </span>1</span>; Poll</span>::</span>Ready(</span>Some</span>(item)) other </span>=></span> other</span>, ited-stream">2. Rate-Limited Stream</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">use </span>tokio</span>::</span>time</span>::</span>{Duration</span>,</span> Instant}</span>; style="color:#fa6e32;">struct </span>RateLimitedStream</span><S> { inner</span>:</span> S, rate</span>:</span> Duration, last_emit</span>: </span>Option</span><Instant>, style="color:#fa6e32;">impl</span><S</span>:</span> Stream> Stream </span>for </span>RateLimitedStream</span><S> { </span>type </span>Item </span>= </span>S</span>::</span>Item</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>let</span> now </span>= </span>Instant</span>::</span>now()</span>; </span>if let </span>Some</span>(last_emit) </span>= </span>self</span>.</span>last_emit { </span>let</span> elapsed </span>=</span> now </span>-</span> last_emit</span>; </span>if</span> elapsed </span>< </span>self</span>.</span>rate { </span>// Not enough time has passed cx</span>.</span>waker</span>()</span>.</span>wake_by_ref</span>()</span>; </span>return </span>Poll</span>::</span>Pending</span>; </span>match unsafe </span>{ Pin</span>::</span>new_unchecked(</span>&</span>mut </span>self</span>.</span>inner) }</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(item)) </span>=> </span>{ </span>self</span>.</span>last_emit </span>= </span>Some</span>(now)</span>; Poll</span>::</span>Ready(</span>Some</span>(item)) other </span>=></span> other</span>, e-considerations">Performance Considerations</a></h2> class="zola-anchor" href="#1-memory-management" aria-label="Anchor link for: 1-memory-management">1. Memory Management</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct </span>ChunkedStream</span><S</span>:</span> Stream> { inner</span>:</span> S, chunk_size</span>: </span>usize</span>, current_chunk</span>: </span>Vec</span><</span>S</span>::</span>Item>, style="color:#fa6e32;">impl</span><S</span>:</span> Stream> Stream </span>for </span>ChunkedStream</span><S> { </span>type </span>Item </span>= </span>Vec</span><</span>S</span>::</span>Item></span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>while </span>self</span>.</span>current_chunk</span>.</span>len</span>() </span>< </span>self</span>.</span>chunk_size { </span>match unsafe </span>{ Pin</span>::</span>new_unchecked(</span>&</span>mut </span>self</span>.</span>inner) }</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(item)) </span>=> </span>{ </span>self</span>.</span>current_chunk</span>.</span>push</span>(item)</span>; Poll</span>::</span>Ready(</span>None</span>) </span>if </span>!</span>self</span>.</span>current_chunk</span>.</span>is_empty</span>() </span>=> </span>{ </span>return </span>Poll</span>::</span>Ready(</span>Some</span>( std</span>::</span>mem</span>::</span>replace(</span>&</span>mut </span>self</span>.</span>current_chunk</span>, </span>Vec</span>::</span>new()) ))</span>; Poll</span>::</span>Ready(</span>None</span>) </span>=> </span>return </span>Poll</span>::</span>Ready(</span>None</span>)</span>, Poll</span>::</span>Pending </span>=> </span>return </span>Poll</span>::</span>Pending</span>, </span>if </span>self</span>.</span>current_chunk</span>.</span>len</span>() </span>== </span>self</span>.</span>chunk_size { Poll</span>::</span>Ready(</span>Some</span>( std</span>::</span>mem</span>::</span>replace(</span>&</span>mut </span>self</span>.</span>current_chunk</span>, </span>Vec</span>::</span>with_capacity(</span>self</span>.</span>chunk_size)) } </span>else </span>{ Poll</span>::</span>Pending d-operations">2. CPU-Bound Operations</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct </span>ComputeBoundStream</span><S, F> { inner</span>:</span> S, transform</span>:</span> F, runtime_handle</span>: </span>tokio</span>::</span>runtime</span>::</span>Handle, style="color:#fa6e32;">impl</span><S, F, T, U> Stream </span>for </span>ComputeBoundStream</span><S, F> style="color:#fa6e32;">where S</span>: </span>Stream<Item = T> + Unpin, F</span>:</span> Fn(T) -> U + Send + </span>'static</span>, T</span>:</span> Send + </span>'static</span>, U</span>:</span> Send + </span>'static</span>, </span>type </span>Item </span>=</span> U</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>match </span>Pin</span>::</span>new(</span>&</span>mut </span>self</span>.</span>inner)</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(item)) </span>=> </span>{ </span>let</span> transform </span>= </span>self</span>.</span>transform</span>.</span>clone</span>()</span>; </span>let</span> handle </span>= </span>self</span>.</span>runtime_handle</span>.</span>clone</span>()</span>; Poll</span>::</span>Ready(</span>Some</span>(handle</span>.</span>block_on</span>(async </span>move </span>{ tokio</span>::</span>task</span>::</span>spawn_blocking(</span>move </span>\|\| </span>transform</span>(item))</span>.</span>await</span>.</span>unwrap</span>() Poll</span>::</span>Ready(</span>None</span>) </span>=> </span>Poll</span>::</span>Ready(</span>None</span>)</span>, Poll</span>::</span>Pending </span>=> </span>Poll</span>::</span>Pending</span>, class="zola-anchor" href="#error-handling" aria-label="Anchor link for: error-handling">Error Handling</a></h2> ble-errors">1. Recoverable Errors</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct </span>RetryStream</span><S> { inner</span>:</span> S, retry_count</span>: </span>usize</span>, max_retries</span>: </span>usize</span>, style="color:#fa6e32;">impl</span><S, T, E> Stream </span>for </span>RetryStream</span><S> style="color:#fa6e32;">where S</span>: </span>Stream<Item = </span>Result</span><T, E>> + Unpin, E</span>: </span>std</span>::</span>error</span>::</span>Error, </span>type </span>Item </span>= </span>Result</span><T, E></span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>loop </span>{ </span>match </span>Pin</span>::</span>new(</span>&</span>mut </span>self</span>.</span>inner)</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(</span>Ok</span>(item))) </span>=> </span>{ </span>self</span>.</span>retry_count </span>= </span>0</span>; </span>return </span>Poll</span>::</span>Ready(</span>Some</span>(</span>Ok</span>(item)))</span>; Poll</span>::</span>Ready(</span>Some</span>(</span>Err</span>(e))) </span>=> </span>{ </span>if </span>self</span>.</span>retry_count </span>< </span>self</span>.</span>max_retries { </span>self</span>.</span>retry_count </span>+= </span>1</span>; </span>continue</span>; </span>return </span>Poll</span>::</span>Ready(</span>Some</span>(</span>Err</span>(e)))</span>; other </span>=> </span>return</span> other</span>, rable-errors">2. Unrecoverable Errors</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct </span>FallibleStream</span><S> { inner</span>:</span> S, error_handler</span>: </span>Box</span><dyn </span>Fn</span>(</span>Box</span><dyn std</span>::</span>error</span>::</span>Error>) </span>+ </span>Send</span>>, style="color:#fa6e32;">impl</span><S</span>:</span> Stream> Stream </span>for </span>FallibleStream</span><S> { </span>type </span>Item </span>= </span>S</span>::</span>Item</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>match unsafe </span>{ Pin</span>::</span>new_unchecked(</span>&</span>mut </span>self</span>.</span>inner) }</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(item)) </span>=> </span>Poll</span>::</span>Ready(</span>Some</span>(item))</span>, Poll</span>::</span>Ready(</span>None</span>) </span>=> </span>Poll</span>::</span>Ready(</span>None</span>)</span>, Poll</span>::</span>Pending </span>=> </span>{ </span>// Handle potential errors during pending state Poll</span>::</span>Pending class="zola-anchor" href="#testing-strategies" aria-label="Anchor link for: testing-strategies">Testing Strategies</a></h2> class="zola-anchor" href="#1-mock-streams" aria-label="Anchor link for: 1-mock-streams">1. Mock Streams</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">#</span>[</span>cfg</span>(test)] style="color:#fa6e32;">mod </span>tests </span>{ </span>use super</span>::</span>; </span>use </span>futures</span>::</span>stream</span>; </span>use </span>std</span>::</span>time</span>::</span>Duration</span>; </span>struct </span>MockStream</span><T> { items</span>: </span>Vec</span><T>, delay</span>:</span> Duration, </span>impl</span><T</span>: </span>Clone</span>> Stream </span>for </span>MockStream</span><T> { </span>type </span>Item </span>=</span> T</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>if </span>self</span>.</span>items</span>.</span>is_empty</span>() { Poll</span>::</span>Ready(</span>None</span>) } </span>else </span>{ tokio</span>::</span>time</span>::</span>sleep(</span>self</span>.</span>delay)</span>.</span>await</span>; Poll</span>::</span>Ready(</span>Some</span>(</span>self</span>.</span>items</span>.</span>remove</span>(</span>0</span>))) </span>#</span>[</span>tokio</span>::</span>test</span>] async </span>fn </span>test_stream_behavior</span>() { </span>let</span> mock </span>=</span> MockStream { items</span>: </span>vec!</span>[</span>1</span>, </span>2</span>, </span>3</span>]</span>, delay</span>: </span>Duration</span>::</span>from_millis(</span>100</span>)</span>, }</span>; </span>let mut</span> stream </span>= </span>BufferedStream</span>::</span>new(mock</span>, </span>2</span>)</span>; </span>assert_eq!</span>(stream</span>.</span>next</span>()</span>.</span>await</span>, </span>Some</span>(</span>1</span>))</span>; </span>assert_eq!</span>(stream</span>.</span>next</span>()</span>.</span>await</span>, </span>Some</span>(</span>2</span>))</span>; </span>assert_eq!</span>(stream</span>.</span>next</span>()</span>.</span>await</span>, </span>Some</span>(</span>3</span>))</span>; </span>assert_eq!</span>(stream</span>.</span>next</span>()</span>.</span>await</span>, </span>None</span>)</span>; -based-testing">2. Property-Based Testing</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">#</span>[</span>cfg</span>(test)] style="color:#fa6e32;">mod </span>tests </span>{ </span>use </span>proptest</span>::</span>prelude</span>::*</span>; </span>proptest! </span>{ </span>#</span>[</span>test</span>] </span>fn </span>test_stream_properties</span>(</span>inputs</span>: </span>Vec</span><</span>i32</span>>) { </span>let</span> stream </span>= </span>stream</span>::</span>iter(inputs</span>.</span>clone</span>())</span>; </span>let</span> buffered </span>= </span>BufferedStream</span>::</span>new(stream</span>, </span>10</span>)</span>; tokio_test</span>::</span>block_on(async { </span>let</span> collected</span>: </span>Vec</span><</span>_</span>> </span>=</span> buffered</span>.</span>collect</span>()</span>.</span>await</span>; </span>prop_assert_eq!</span>(inputs</span>,</span> collected)</span>; })</span>; ices-and-optimizations">Best Practices and Optimizations</a></h2> class="zola-anchor" href="#1-stream-fusion" aria-label="Anchor link for: 1-stream-fusion">1. Stream Fusion</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct </span>FusedStream</span><S> { inner</span>:</span> S, is_terminated</span>: </span>bool</span>, style="color:#fa6e32;">impl</span><S</span>:</span> Stream> Stream </span>for </span>FusedStream</span><S> { </span>type </span>Item </span>= </span>S</span>::</span>Item</span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>if </span>self</span>.</span>is_terminated { </span>return </span>Poll</span>::</span>Ready(</span>None</span>)</span>; </span>match unsafe </span>{ Pin</span>::</span>new_unchecked(</span>&</span>mut </span>self</span>.</span>inner) }</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>None</span>) </span>=> </span>{ </span>self</span>.</span>is_terminated </span>= </span>true</span>; Poll</span>::</span>Ready(</span>None</span>) other </span>=></span> other</span>, class="zola-anchor" href="#2-batch-processing" aria-label="Anchor link for: 2-batch-processing">2. Batch Processing</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct </span>BatchProcessor</span><S> { inner</span>:</span> S, batch_size</span>: </span>usize</span>, current_batch</span>: </span>Vec</span><</span>S</span>::</span>Item>, style="color:#fa6e32;">impl</span><S</span>:</span> Stream> Stream </span>for </span>BatchProcessor</span><S> { </span>type </span>Item </span>= </span>Vec</span><</span>S</span>::</span>Item></span>; </span>fn </span>poll_next</span>( </span>mut </span>self</span>: Pin<</span>&</span>mut Self</span>>, </span>cx</span>: </span>&</span>mut </span>Context<'</span>_</span>> ) </span>-> </span>Poll<</span>Option</span><</span>Self</span>::</span>Item>> { </span>while </span>self</span>.</span>current_batch</span>.</span>len</span>() </span>< </span>self</span>.</span>batch_size { </span>match unsafe </span>{ Pin</span>::</span>new_unchecked(</span>&</span>mut </span>self</span>.</span>inner) }</span>.</span>poll_next</span>(cx) { Poll</span>::</span>Ready(</span>Some</span>(item)) </span>=> </span>{ </span>self</span>.</span>current_batch</span>.</span>push</span>(item)</span>; Poll</span>::</span>Ready(</span>None</span>) </span>if </span>!</span>self</span>.</span>current_batch</span>.</span>is_empty</span>() </span>=> </span>{ </span>return </span>Poll</span>::</span>Ready(</span>Some</span>( std</span>::</span>mem</span>::</span>replace(</span>&</span>mut </span>self</span>.</span>current_batch</span>, </span>Vec</span>::</span>new()) ))</span>; Poll</span>::</span>Ready(</span>None</span>) </span>=> </span>return </span>Poll</span>::</span>Ready(</span>None</span>)</span>, Poll</span>::</span>Pending </span>=> </span>{ </span>if </span>!</span>self</span>.</span>current_batch</span>.</span>is_empty</span>() { </span>return </span>Poll</span>::</span>Ready(</span>Some</span>( std</span>::</span>mem</span>::</span>replace(</span>&</span>mut </span>self</span>.</span>current_batch</span>, </span>Vec</span>::</span>new()) ))</span>; </span>return </span>Poll</span>::</span>Pending</span>; Poll</span>::</span>Ready(</span>Some</span>( std</span>::</span>mem</span>::</span>replace(</span>&</span>mut </span>self</span>.</span>current_batch</span>, </span>Vec</span>::</span>with_capacity(</span>self</span>.</span>batch_size)) class="zola-anchor" href="#pros-and-cons" aria-label="Anchor link for: pros-and-cons">Pros and Cons</a></h2> class="zola-anchor" href="#pros" aria-label="Anchor link for: pros">Pros:</a></h3> Processing</strong></p> fit for I/O-bound operations</li> resource utilization</li> bility</strong></p> to chain transformations</li> with async/await</li> Efficiency</strong></p> fusion opportunities</li> class="zola-anchor" href="#cons" aria-label="Anchor link for: cons">Cons:</a></h3> ity</strong></p> complex than Iterator</li> Overhead</strong></p> allocation for futures</li> Curve</strong></p> async concepts</li> class="zola-anchor" href="#conclusion" aria-label="Anchor link for: conclusion">Conclusion</a></h2> Stream</code> is a powerful abstraction for async programming in Rust, offering:</p> handling of asynchronous sequences</li> composition capabilities</li> performance characteristics</li> it requires careful consideration of:</p> to successful usage is understanding these trade-offs and choosing appropriate patterns for your specific use case.</p> your stream implementations</li> edge cases thoroughly</li> backpressure mechanisms</li> errors appropriately</li> for your specific use case</li> overview shoul</p> I gave a talk titled "Don't Block, Just Flow: Embracing Asynchronous with Rust Streams." It focused on using futures::stream::Stream in Rust.</p> The talk covered the importance of I/O concurrency for all applications, pinning and boxing of dynamic types, the relationship between Send and Sync with streams, and backpressure handling. In general, it explored how futures::stream::Stream is used, the practical utilities it offers for applications, and the issues it helps address.</p> For those interested in learning more, you can find resources here: </a></p>

artech

Dealing with Panics 🔥 in async rust 🦀

2024-12-09T00:00:00+00:00

You might have come across the term "fearless concurrency" quite often if you have some background in Rust, but nothing is absolute in this world, and neither is concurrency. Additionally, it's very unlikely to find the term "fearless async concurrency" in Rust's ecosystem. So it's becomes nessecary to know how to manage some spooky panics, Let's delve deeper into this.

Problem at Hand</a></h1>
While working with some async codebases, your logical definition of code might have some quirky or spooky possibility of panicking somewhere or at some part of the code. This could be anticipated in advance or maybe totally undetected. As illustrated with the example below, let's study it to find out more about it.
async fn fetch_all_post(n: u32) { let pagination_factor = 4; let pagination_stub_factor: u32 = (n / 4) as u32; let url = format!("https://random_domain.com/posts/pagination/{}", pagination_stub_factor); let _res = reqwest::get(url.into()).await; } </code></pre> In the above example, we can see that we are trying to determine the pagination factor for a given URL (just as an example). If you are a bit experienced, you may have already spotted the problem present here! Let's look at those:

What if pagination_factor</code> is greater than n</code>?</li>
There could be problems in casting f32</code> to u32</code>.</li> </ul> We will focus on the first point since it's easier to prove the point. Imagine that you update your code with some assert statement like this, which could panic if any value we supply is checked against pagination_factor</code>.async fn fetch_all_post(n: u32) { let pagination_factor = 4; assert!(n >= pagination_factor); let pagination_stub_factor: u32 = (n / 4) as u32; let url = format!("https://random_domain.com/posts/pagination/{}", pagination_stub_factor); let _res = reqwest::get(url.into()).await; } </code></pre> Hmm, looks fine now but we still havn't eliminated the possibilty of panicking in our code Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.25s Running `target/debug/playground` thread 'main' panicked at src/main.rs:16:5: assertion failed: n >= pagination_factor </code></pre> This was just a very straight forward example we saw, but in real world we have have something as serious as socket unavailable, file not found or what not! Somehow we should be able to control the consequence of panic, we will study those in the coming sections. Async Runtime and Panic Handling Strategy</a></h1> If you are writing async Rust, then you have to choose an async executor which will run your futures/async tasks forward. Below is a list of some widely adopted and often used executors: tokio</li> async-std</li> smol-rs</li> </ul> Each async executor has its own strategy for dealing with panics that occur within an async block. With Tokio, if a panic occurs, it isolates the given task. The runtime doesn't shut down (though this behavior can be modified) and continues to operate while printing the standard error message to standard out, simply restarting. The case with async-std is the same as above, where tasks are isolated based on how they are spawned. If a panic occurs in some task, it won't crash the entire runtime, and other tasks would simply restart and continue from that point onwards. For smol-rs, it deals with panics similarly to how the above two handle them, except with some internal exceptions. But mostly, for all the tasks (futures) which are spawned using these runtimes, a handle is returned which can carry the panic message as an Err</code> variant as described below. //assuming we are in some async context or block already let join_handle: tokio::task::JoinHandle<()> = tokio::task::spawn( async move { panic!("some error") //we panic inside our task } ); // we get a result type whose error variant is of std::any::Any type let res: Result<(), Box<dyn std::any::Any>> = join_handle.await; </code></pre> Looking at the above example, we find that during panics, it gets converted to the trait object std::any::Any</code>, which can universally represent any type. Later, you may downcast it based on your error handling strategy. As you can see, the runtime does give you these abilities, and this is valid for most runtimes since these tasks are isolated from each other. Note: Error types passed from panic!(..)</code> might look easy to deal with, but it is an expensive operation to convert from Box<dyn std::any::Any></code> to some other type. If you are designing your application to be performant, you may require something more direct that you can control. std::panic::catch_unwind to your rescue</a></h1> We briefly looked over how runtimes deal with futures that may panic, but luckily we have more control already available if you wish to avoid the route of runtime handling panics of your future. To give it a simple start, there can be some suspicious part of the code where we suspect that it might panic somehow! Let's check out the previous example again. 1 async fn fetch_all_post(n: u32) { 2 let pagination_factor = 4; 3 assert!(n >= pagination_factor); 4 let pagination_stub_factor: u32 = (n / 4) as u32; 5 let url = format!("https://random_domain.com/posts/pagination/{}", pagination_stub_factor); 6 7 let _res = reqwest::get(url.into()).await; } </code></pre> Here we know line number 3 might panic based on user input. To prevent this from happening, we can simply wrap this part of the code in the std::panic::catch_unwind</code> function like this: 1 async fn fetch_all_post(n: u32) { 2 let url = std::panic::catch_unwind(|| 3 let pagination_factor = 4; 4 assert!(n >= pagination_factor); 5 let pagination_stub_factor: u32 = (n / 4) as u32; 6 format!("https://random_domain.com/posts/pagination/{}", pagination_stub_factor) 7 ); 8 9 match url_block { 10 Ok(url_val) => { 11 let _res = reqwest::get(url_val.into()).await; 12 } 13 Err(err) => { 14 println!("some error: {}", err); 15 } 16 }; } </code></pre> So what's changed now 🤔? We wrapped lines 2-5 (of the original method) into the catch_unwind</code> method and returned the computed URL by performing matching on it since it is a result type. If line 4 panics, we won't crash or show an error message on our async runtime. Instead, this will be handled within our code by ourselves. Let's now check out the definition of std::panic::catch_unwind</code> from the std library: pub fn catch_unwind<F: FnOnce() -> R + UnwindSafe, R>(f: F) -> Result<R> </code></pre> Here you will observe two generics: F</code>, which accepts a closure and returns R</code>, which should also implement the UnwindSafe</code> trait (we will discuss this in more detail). Interestingly, the return type here has to be the following: pub type Result<T> = Result<T, Box<dyn Any + Send + 'static>>; </code></pre> Basically, the Result type is aliased to have the error variant be thread-safe if encountered. Hmm, so now you see how powerful std::panic::catch_unwind</code> can be. Remember, this is just a single example; there could be several more possibilities depending on how you wish to handle such panics. Using catch_unwind with your futures</a></h1> Earlier, we saw how we can manually establish control over panics and produce a Result type as a consequence, but something even more convenient is already available for you from the Futures</code> crate. This is the catch_unwind()</code></a> method, which creates an intermediate object CatchUnwind<Fut></code></a> that implements futures::future::Future</code></a>. Hence, after awaiting it, it produces a result as shown in the description below. impl<Fut> Future for CatchUnwind<Fut> where Fut: Future + UnwindSafe, { //notice the output type here type Output = Result<Fut::Output, Box<dyn Any + Send>>; fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { ... } } </code></pre> For the associated type Output</code>, it returns the Ok</code> variant with the output for which this was called, and the Err</code> variant is again a Box<dyn Any + Send></code> trait object that can be sent anywhere. Now let's see it in action. use futures::future::FutureExt; 1 async fn fetch_all_post(n: u32) { 2 3 let catch_url_block: Result<String, Box<dyn Any + Send>> = async move { 4 let pagination_factor = 4; 5 assert!(n >= pagination_factor); 6 let pagination_stub_factor: u32 = (n / 4) as u32; 7 let url = format!("https://random_domain.com/posts/pagination/{}", pagination_stub_factor); 8 }.catch_unwind().await; // we apply catch_unwind to this 9 10 match url_block { 10 Ok(url_val) => { 11 let _res = reqwest::get(url_val.into()).await; 12 } 13 Err(err) => { 14 println!("some error: {}", err); 15 } 16 }; 17 } </code></pre> Look at line number 8, you will find that we have used .catch_unwind()</code>. Now we can also call .await</code> on the CatchUnwind</code> object. We can apply catch_unwind</code> on any type that implements the Future</code> trait. This can be smartly chained with other futures to create a more complex expression that can be later awaited for a response. Let's check out an example of catch_unwind</code> with streams: 1 2 let mut client = futures::stream::unfold(0, |count| async move { 3 let next_count = count + 1; 4 // peform some expensive work ... 5 Some((count, next_count)) // this will return count from it 6 }); 7 8 let mut responses: Vec<i32> = client 9 .catch_unwind() 10 .filter_map(|val| val.ok()) // convert Result<i32, Box<dyn Any + Send>> to Option<i32> 11 .take(50) 12 .collect() 13 .await; 14 </code></pre> In the above example, you see how we are using streams in the future to compute something. You might wonder how catch_unwind</code> is implementable on something like future::stream::StreamExt</code>. Note that this method is also available under futures::stream::StreamExt</code></a>. On line 10, we convert Result<i32, Box<dyn Any + Send>></code> to Option<i32></code> type simply because the filter_map</code></a> method requires us to pass any data encapsulated as an option type. Then, we take 50 of those and collect them. This example was too straightforward, honestly, but the quirky nature of this method is not yet revealed. Let's check out a more realistic example that does something more interesting... let mut client = futures::stream::unfold(0, |count| async move { let next_count = count + 1; let url = format!("https://dummyjson.com/quotes/random"); let req = reqwest::get(url).await; // if this panics ! Some((req, next_count)) }); async fn filter_posts( catch_unwind_req: Result<Result<Response, reqwest::Error>, Box<dyn Any + Send>> ) -> Option<String> { match catch_unwind_req { Ok(Ok(response)) => { response.text().await.ok() //convert from Result<T,E> to Option<T> } _ => { None } } } let mut responses: Vec<String> = client .catch_unwind() .filter_map(filter_posts) .take(50) .collect() .await; </code></pre> Above is a good example regarding how catch_unwind</code> could be potentially used in this!, Let's run this first | fn catch_unwind(self) -> CatchUnwind<Self> | ------------ required by a bound in this associated function 1324 | where 1325 | Self: Sized + std::panic::UnwindSafe, | ^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `StreamExt::catch_unwind` </code></pre> An error, hmmm... This is one of the problems that shows up. Let's revisit the definition of catch_unwind</code> again: pub fn catch_unwind<F: FnOnce() -> R + UnwindSafe, R>(f: F) -> Result<R> </code></pre> You will see the UnwindSafe</code> trait has to be applied to the return type! If you visit the definition of reqwest::Response</code></a>, it contains a negative implementation for !UnwindSafe</code>, hence it can't be sent across the catch_unwind</code> boundary. Now you might think, is there a way around this? Well, the answer is not that simple, but there exists a solution! Welcome std::panic::AssertUnwindSafe</code></a>. pub struct AssertUnwindSafe<T>(pub T); impl<T> UnwindSafe for AssertUnwindSafe<T> {} </code></pre> Type std::panic::AssertUnwindSafe</code> implements the UnwindSafe</code> trait even if the type contains !UnwindSafe</code>. So, if a type implements !UnwindSafe</code>, it can be wrapped in this type and returned from the catch_unwind</code> boundary. Coming back to our previous example, let's modify it to support the usage of AssertUnwindSafe</code> here: // we wrap our UnFold type into AssertUnwindSafe let mut client = AssertUnwindSafe(futures::stream::unfold(0, |count| async move { let next_count = count + 1; let url = format!("https://dummyjson.com/quotes/random"); let req = reqwest::get(url).await; // if this panics ! Some((req, next_count)) })); async fn filter_posts( catch_unwind_req: Result<Result<Response, reqwest::Error>, Box<(dyn Any + Send + 'static)>> ) -> Option<String> { match catch_unwind_req { Ok(Ok(response)) => { response.0.text().await.ok() //convert from Result<T,E> to Option<T> } _ => { None } } } let mut responses: Vec<String> = client .catch_unwind() // check each post incoming .filter_map(filter_posts) .take(50) .collect() .await; </code></pre> We have modified the client</code> type to be wrapped under AssertUnwindSafe</code>. Under the hood, the futures::stream::unfold</code> method returns an object future::stream::Unfold</code></a>. Here, we have also utilized filter_map</code> for filtering out, but there is a catch! Let's see that too! If we explicitly perform a panic just for the sake of testing, we will find something very interesting happening. The example below is taken from the official docs! use futures::stream::{self, StreamExt}; let stream = stream::iter(vec![Some(10), None, Some(11)]); // Panic on second element let stream_panicking = stream.map(|o| o.unwrap()); // Collect all the results let stream = stream_panicking.catch_unwind(); let results: Vec<Result<i32, _>> = stream.collect().await; match results[0] { Ok(10) => {} _ => panic!("unexpected result!"), } assert!(results[1].is_err()); assert_eq!(results.len(), 2); </code></pre> This is something where you can find it problematic to deal with. The official docs for futures::stream::catch_unwind</code></a> mention the following: Caught panic (if any) will be the last element of the resulting stream So you have to know how to use it correctly if you wish to utilize this. Panic hooks</a></h1> Remember the topic we covered earlier about async runtime panic handling? That topic only contained information regarding how the runtime internally handled panics. For example, to go more in-depth, the Tokio runtime builder object tokio::runtime::Builder::unhandled_panic</a> gives you a method for dealing with panics that might happen within Tokio's async runtime context. Though unstable, it is still available. Interestingly, we have another technique available specifically to deal with this: introducing panic hooks. pub fn set_hook(hook: Box<dyn Fn(&PanicHookInfo<'_>) + Sync + Send + 'static>) </code></pre> If somewhere within your codebase there happens to be a panic, this hook will be called automatically. The signature of this method is straightforward; it accepts a boxed closure with a signature where the type must be Send</code> and Sync</code> compatible. Let's see an example of this. std::panic::set_hook(Box::new(|panic_info| { let timestamp = chrono::Local::now().format("%Y-%m-%d %H:%M:%S"); let backtrace = backtrace::Backtrace::new(); let panic_message = format!("[{}] Panic: {}\nBacktrace:\n{:?}\n\n", timestamp, panic_info, backtrace); // Log to file if let Ok(mut file) = OpenOptions::new() .create(true) .append(true) .open("panic.log") { let _ = file.write_all(panic_message.as_bytes()); } })); fn process_request() { panic!("Database connection failed"); // Example panic } </code></pre> In the above example, we are calling a panic hook to generate a timestamp and backtrace, then format this and write it out to a file. Essentially, we are logging any panics that occur. No matter at what point in the code a panic is triggered, set_hook</code> will be invoked automatically. set_hook</code> is more powerful in a way that it supports obtaining references to the type which was passed under panic</code> macro, here is a example for that panic::set_hook(Box::new(|panic_info| { if let Some(s) = panic_info.payload().downcast_ref::<&str>() { println!("panic occurred: {s:?}"); } else if let Some(s) = panic_info.payload().downcast_ref::<String>() { println!("panic occurred: {s:?}"); } else { println!("panic occurred"); } })); panic!("Normal panic"); </code></pre> In the above, we panic with a &str</code> message and later call the payload</code> method over it, which returns &(dyn Any + Send)</code>. We can then apply downcast_ref</code> to obtain a read-only reference for that type. Here is another example with a Vec<i32></code>: std::panic::set_hook(Box::new(|panic_info| { if let Some(s) = panic_info.payload().downcast_ref::<Vec<i32>>() { println!("panic occurred: {:?}", s); } else { println!("panic occurred with unknown payload"); } })); let val = vec![1,2,3,4,5]; std::panic::panic_any(val); </code></pre> If you notice, in the last line we have utilized the std::panic::panic_any</code></a> method rather than the panic</code> macro. This is because the panic</code> macro only allows string literals to be passed within itself, whereas std::panic::panic_any</code> allows us to use 'static + Any + Send</code> as our argument. If you are wondering what the purpose of std::any::Any</code> is, you may check out this</a> blog post. I hope you learnt something interesting and useful through this blog post, feel free to share your thoughts with me ;)

AsRef vs Borrow vs Deref Busted 2024-12-06T00:00:00+00:00 It is common to encounter a situation where you may require to return a different type either as a immutable or mutable reference which can be a field of a struct or a completely new type composed out of a given type for some operation You may also have come across such type expression impl AsRef<str></code> or where T: Borrow<[u8]></code> or something like impl Deref<Target = [u8]></code> these kinds of expression are common to come across which can be tricky sometimes to understand and draw a distinction among it. It's quite common to come across these traits in standard library AsRef<T></code> / AsMut<T></code>, Borrow</code> / BorrowMut</code> and Deref</code> / DerefMut</code>. Unless you have good background with rust, The first thought which may come to mind after looking at these traits is they are naturally made for producing a subtype or newtype from a given type when called! well this is unfortunately not true. If this was true then standard library won't be having these many traits! Similarity</a></h1> But before we start to look over there characteristics and differences, Let's cover there similarities first, keep this in mind following similarities are not strongly same but similar or close to being similar depending upon situation, and in some simple situations could be used interchangibely, let's check them out ! Simplification of borrow: All the above traits are used to simplify access to data. They allow for different ways of referring to an object, typically without taking ownership of real one. with AsRef & AsMut</li> </ul> impl AsRef<Car> for FourWheeler { ... } </code></pre> with Borrow trait</li> </ul> impl Borrow<Car> for FourWheeler { ... } </code></pre> with Deref and DerefMut</li> </ul> impl Deref for FourWheeler { type Target = Car; ... } </code></pre> </li> </ul> Conversion support to Non-sized types: Each trait definition allows conversion to non-sized types, as shown in the definition of each trait bellow, you will notice this. With AsRef</code> & AsMut</code></li> </ul> pub trait AsRef<T> where T: ?Sized, // Non-sized type { // Required method fn as_ref(&self) -> &T; } </code></pre> pub trait AsMut<T> where T: ?Sized, // Non-sized type { // Required method fn as_mut(&mut self) -> &mut T; } </code></pre> With Borrow</code> & BorrowMut</code> trait</li> </ul> pub trait Borrow<Borrowed> where Borrowed: ?Sized, // Non-sized type { // Required method fn borrow(&self) -> &Borrowed; } </code></pre> pub trait BorrowMut<Borrowed>: Borrow<Borrowed> where Borrowed: ?Sized, // Non-sized type { // Required method fn borrow_mut(&mut self) -> &mut Borrowed; } </code></pre> With Deref</code> & DerefMut</code></li> </ul> pub trait Deref { type Target: ?Sized; // Non-sized type // Required method fn deref(&self) -> &Self::Target; } </code></pre> pub trait DerefMut: Deref { // Required method fn deref_mut(&mut self) -> &mut Self::Target; } </code></pre> </li> Used in Generic Programming: All three traits are highly useful in generic programming, where you want to write functions or structs that can operate on references to data rather than the data itself. With AsRef</code> & AsMut</code> you may have the impelmentation for any given type such following</li> </ul> //case 1 impl AsRef<str> for T { ... } //case 2 fn compute<T>(s: impl AsRef<T>) where T: ToString .. //case 3 struct Car { tires: Box<dyn AsRef> ... } </code></pre> with Borrow</code> & BorrowMut</code> traits you can still acheive same exact thing as above </li> with Deref</code> & DerefMut</code> things get bit special due to associated type in it's signature definition </li> </ul> //case 1 impl<Y> Deref for SomeType where Y: std::fmt::Debug { type Target = Y; fn deref(&self) -> &Self::Target { ... } } //case 2 fn accept_deref(s: impl Deref<Target=U>) where U: ToString ... //case 3 struct Truck { tires: Box<dyn Deref<Target = I>> ... } </code></pre> </li> </ul> AsRef vs Borrow vs Deref in Rust</a></h1> AsRef & AsMut trait</a></h2> AsRef</code> is a trait for performing cheap reference-to-reference conversions. This includes read and write borrows! It's most commonly used for functions that can accept multiple types of concrete references. It can also be used to borrow non-sized types! Let's check out a simple example first. In the example below, we are trying to borrow a type as a str</code>, but we are allowed to pass each type as a reference as illustrated below. Common Use Cases</a></h3> fn process_string<T: AsRef<str>>(s: T) { let s_ref: &str = s.as_ref(); // Process the string slice } // Can be called with different types let string = String::from("hello"); let str_literal = "world"; process_string(&string); // works process_string(str_literal); // also works </code></pre> In the above example, we have seen how we can pass around all those types that implement AsRef</code>. These types are now qualified to be passed as owned types, and later, using the as_ref()</code> method, we can call that type to be represented as the intended type as a read-only reference. Since there exist implementations for &str</code> and String</code> types as shown below: impl AsRef<str> for String { #[inline] fn as_ref(&self) -> &str { self } } </code></pre> and for str</code> type impl AsRef<str> for str { #[inline(always)] fn as_ref(&self) -> &str { self } } </code></pre> Interestingly, if you observe carefully here, you will find that AsRef</code> doesn't write the following type signature for the generic position AsRef<&str></code> instead, it writes AsRef<str></code>. If you are wondering why this is, check out these two posts respectively: Rust nomicon reference</a> and Niko Matsakis</a>, to understand the difference. Now, if you look at the trait function fn as_ref(&self) -> &str</code>, it returns a borrowed version. Frankly, the explanation behind how str</code> is borrowed into &str</code> deserves its own post, but to give a short answer: inside the method, self</code> is already of type &str</code> because we're implementing a method that takes &self</code>, so we can just return it directly since it matches the return type. Now let's move our attention towards AsMut</code>, which lets us borrow a type mutably. If you visit the standard library, you will find there exist implementations for AsMut</code> for str</code> and String</code> types. These implementations are as follows: For the string type: impl AsMut<str> for String { #[inline] fn as_mut(&mut self) -> &mut str { self } } </code></pre> for str type impl AsMut<str> for str { #[inline(always)] fn as_mut(&mut self) -> &mut str { self } } </code></pre> Interestingly, this time we borrow both of our types as mutable references &mut str</code>. By now, I am hoping this has brought some clarity regarding how the AsRef</code> and AsMut</code> traits can be used. The real power of these traits lies in their flexibility regarding how they can be used. Pay attention to how AsRef</code> and AsMut</code> are totally independent of each other, meaning they don't have any associated type dependency or super trait requirement, unlike what we previously saw for the Borrow</code>, BorrowMut</code>, Deref</code>, and DerefMut</code> traits. Hence, we are given complete flexibility in how one concrete type can be cheaply converted into another type. Let's understand this explanation through an example. Let's think of a situation where you wish to convert a book type Book</code> into some primitive representation such as &str</code> as an immutable borrow only, and also as Vec<String></code> as a mutable reference. struct Book { title: String, pages: Vec<String>, } </code></pre> writing a simple AsRef</code> conversion is possible, given if it makes sense to use that type temporarly impl AsRef<str> for Book { fn as_ref(&self) -> &str { &self.title // We can reference the title as a &str } } </code></pre> in a simple manner it is possible to write a AsMut<Vec<String>></code> conversion as well // Implement AsMut<Vec<String>> for Book to modify pages impl AsMut<Vec<String>> for Book { fn as_mut(&mut self) -> &mut Vec<String> { &mut self.pages // We can get a mutable reference to pages } } </code></pre> following from previous, it is possible to write a AsMut<[str]></code> conversion as well impl AsMut<[String]> for Book { fn as_mut(&mut self) -> &mut [String] { &mut self.pages // We can get a mutable reference to pages } } </code></pre> Points to note while using AsRef & AsMut</a></h3> Usage of these traits is best suited when you have to derive a type that is mostly a field of a struct, and the conversion doesn't involve any expensive computation.</li> These traits give you flexibility in usage, meaning you may have a single AsRef</code> for some type, whereas you may have several AsMut</code> for distinct types, and they don't depend on each other in any way!</li> It's better to avoid writing these traits for Non-Sized</code> types such as &dyn ..</code> or &mut dyn..</code>.</li> </ul> Borrow & BorrowMut</a></h2> The Borrow</code> trait is similar to the AsRef</code> trait in that it supports borrowing of type A into type B, but the catch is that it lets you borrow rather than convert something. Hence, the point of comparison shall be between how to distinguish between borrowing and conversion. Conversion of any type to another type is straightforward since it doesn't enforce us to carry any further semantic information, while borrowing shall satisfy such norms. From the above information, Borrow</code> is similar to AsRef</code> but with an additional contract: the borrowed form must hash, compare, and order the same as the owned form. Let's check out its definition first. pub trait Borrow<Borrowed: ?Sized> { fn borrow(&self) -> &Borrowed; } </code></pre> In above definition we have declared out borrow to be a generic just like AsRef</code> which can be Non-sized type and borrows immutably, but we would also need to borrow mutably, let's checkout the definition for BorrowMut</code> trait in detail pub trait BorrowMut<Borrowed>: Borrow<Borrowed> where Borrowed: ?Sized, { // Required method fn borrow_mut(&mut self) -> &mut Borrowed; } </code></pre> For the BorrowMut</code> definition, as we can clearly observe, it depends on the Borrow<Borrowed></code> implementation, which is generic over Borrowed</code>. Therefore, types that are going to implement BorrowMut<Borrowed></code> must first implement the immutable version, i.e., Borrow<Borrowed></code>. This enforces a type to be borrowable in both forms, i.e., &T</code> and &mut T</code>, unlike the AsRef</code> and AsMut</code> traits, which can be totally independent of each other and have no correlation between them. Let's check out the std::collections::HashMap</code> definition regarding the Borrow</code> trait. Use Cases</a></h3> // struct definition pub struct HashMap<K, V, S = RandomState> // method get definition pub fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V> where K: Borrow<Q>, // Observe how Borrow trait is used Q: Hash + Eq, { ... } </code></pre> The type definition of HashMap<K, V></code> is generic over three parameters, but we will only consider K</code> and V</code>, which are for key and value respectively, for simplicity. Now, if we look at the method get</code>, it declares another generic Q</code> which can be borrowed from k</code>, and Q</code> must implement Hash + Eq</code> traits as bounds, since it requires that keys can be distinguishable. This requirement is present for multiple methods of collection types within the standard library. Note: Borrow</code> & BorrowMut</code> themselves do not enforce the semantic requirements through their definitions. It is up to the defining method or struct to declare how semantics are going to be enforced via them. Borrow traits can also be useful for types where we want to retrieve an internal type rather than a composed one, such as for Vec<T></code>, which can be borrowed as a mutable slice &mut [T]</code> and modified directly rather than converting it first. Points to note</a></h3> Stricter semantic requirements, though not required by default.</li> Essentially used for collection types such as HashMap and BtreeMap.</li> Useful when you need to work on a subtype of some composed type which might require modification.</li> There may exist several definitions for a given type to be borrowed in different types.</li> </ol> Deref & DerefMut</a></h2> The trait Deref</code> is one of my personal favorites and quite a powerful one among all. Deref</code> is used for dereferencing operations using the *</code> operator and for automatic dereferencing to a defined type. Unlike traits Borrow</code> & AsRef</code>, Deref</code> carries an associated type as part of its definition and can only be applied once. Let's check out its definition. pub trait Deref { type Target: ?Sized; fn deref(&self) -> &Self::Target; } </code></pre> In the above definition it returns a associated type as immutable reference, now let's take a look for DerefMut</code> pub trait DerefMut: Deref { // Required method fn deref_mut(&mut self) -> &mut Self::Target; } </code></pre> As you can clearly see, just like BorrowMut</code>, DerefMut</code> also depends on Deref</code> to be pre-implemented for a type. Interestingly, the return type belongs to the super trait Deref</code>, which can be borrowed mutably. This has two major advantages: The output type for both borrows can't be changed since it is based on the associated type.</li> It prevents the implementation from existing for more than one type.</li> </ul> To find out more about how associated types are different from generics, I recommend you read this blog here</a>. Once a type implements deref traits, it can now automatically call the methods of dereferenced types using the dot .</code> operator. Let's look at a simple example here. Common Use Cases</a></h3> use std::ops::Deref; struct MyBox(Vec<u8>); impl MyBox { pub fn my_box_len(&self) -> usize { self.0.len() } } impl Deref for MyBox { type Target = Vec<u8>; fn deref(&self) -> &Self::Target { &self.0 } } let mut x = MyBox(vec![4]); // valid let len_one = x.my_box_len(); // also valid, we are directly Vec::len() method since it only takes &self let len = x.len() </code></pre> Incase we require some mutable borrows impl DerefMut for MyBox { fn deref_mut(&mut self) -> &mut Self::Target { &mut self.0 } } </code></pre> now we can call any mutable method over Vec<u8></code> let _val = x.remove(0); // x -> .remove() </code></pre> Those types which implement Deref</code> trait are automatically qualified to use *</code> operator for explicit dereferencing, let _val = (*x).remove(0); // x -> Vec<u8> -> .remove() </code></pre> Now you might wonder why both expressions are making valid calls to remove</code>. Once a type implements the Deref</code> trait, it will attempt to call the respective method through implicit dereferencing if required and will make multiple attempts if the subtype also implements Deref</code>. Here is a straightforward example: let _val: Option<&mut u8> = x.last_mut(); // x -> Vec<u8> -> &mut [u8] </code></pre> If you visit Vec<u8></code>, you will find that it implements Deref<Target=[u8]></code></a>, hence all the methods on &mut [u8]</code> are directly accessible to us. This is very useful, but if not used cautiously, it could be the cause of bugs sometimes, since you may call methods on some other type other than the desired type! Luckily, in such cases, only methods that are first observed through implicit dereference are called. Deref Coercion</a></h3> One of the most powerful features of Deref</code> is onsite coercion if a type implements deref traits. This could be helpful where we wish to avoid explicit casting/conversions: fn takes_str(s: &str) { println!("{}", s); } let string = String::from("hello"); takes_str(&string); // Works because String: Deref<Target=str> takes_str("string2"); // also works because it is a concrete type </code></pre> But hold on a second, why would we need such an onsite coercion feature if we already have AsRef</code> and Borrow</code> traits to take care of the job? Well, I'm glad you asked! If you observe the above definition carefully, you will notice it is a concrete type, which is &str</code>. However, for AsRef</code> and Borrow</code> traits, you will need to have a type that must implement them anyhow, therefore limiting the application and optimizations available. Deref coercion is a powerful language feature if used correctly, you can read more about it here</a> Now that we have built some understanding around it, let's quickly compare them through a simple table. Comparison Table</a></h2> Trait</th> Primary Purpose</th> Key Characteristics</th></tr></thead> AsRef</code></td> Cheap reference conversions</td> - No guarantees about equality or hashing - Useful for generic functions accepting references</td></tr> Borrow</code></td> Borrowed data equivalence</td> - Guarantees about equality and hashing - Essential for collections types like HashMap/BtreeMap</td></tr> Deref</code></td> Smart pointer functionality</td> - Enables *</code> operator - Enables deref coercion - Affects method resolution</td></tr> </tbody></table> Common Gotchas</a></h2> Deref Coercion Costs</li> </ol> // Multiple deref coercions can have performance implications let s = Box::new(String::from("hello")); takes_str(&s); // Box -> String -> str, two dereferences </code></pre> Borrow vs AsRef Choice</li> </ol> // Wrong choice for HashMap key type fn bad_design<T: AsRef<str>>(map: &HashMap<T, u32>) {} // Won't work well // Correct choice fn good_design<T: Borrow<str>>(map: &HashMap<T, u32>) {} </code></pre> Deref for Non-Pointer Types</li> </ol> // Generally avoid implementing Deref for non-pointer-like types // Could be confusing for other developers struct Seconds(u64); // Avoid this: impl Deref for Seconds { type Target = u64; fn deref(&self) -> &u64 { &self.0 } } </code></pre> Summary</a></h2> This overview covers the main differences and use cases for these three important Rust traits. The key is understanding their specific purposes and contracts to use them effectively in your code. Understanding panic handling in larger codebase 2024-07-05T00:00:00+00:00 Comprehensive Guide to Panic Handling in Async Rust</a></h1> Introduction</a></h2> Panic handling in async Rust requires special consideration, especially in larger codebases where reliability and graceful error handling are crucial. This guide explores various aspects of panic handling, including best practices, common scenarios, and practical solutions. Understanding Panics in Rust</a></h2> What is a Panic?</a></h3> fn example_panic() { panic!("This is a panic!"); // Explicit panic let v = vec![1, 2, 3]; v[99]; // Runtime panic: index out of bounds } </code></pre> Common Panic Scenarios</a></h3> Array/Vector Index Out of Bounds</li> </ol> fn array_panic() { let arr = [1, 2, 3]; let index = 5; println!("{}", arr[index]); // PANIC! } </code></pre> Integer Overflow in Debug Mode</li> </ol> fn overflow_panic() { let x: u8 = 255; let y = x + 1; // PANIC in debug mode } </code></pre> Unwrap on None</li> </ol> fn unwrap_panic() { let opt: Option<i32> = None; opt.unwrap(); // PANIC! } </code></pre> Panic Handling in Async Context</a></h2> The Challenge with Async Panics</a></h3> Async code introduces additional complexity because panics can occur in different contexts: Task Panics</li> </ol> async fn task_panic() { tokio::spawn(async { panic!("Task panic!"); }); } </code></pre> Future Panics</li> </ol> async fn future_panic() -> Result<(), Box<dyn std::error::Error>> { let future = async { panic!("Future panic!"); }; future.await } </code></pre> Implementing Robust Panic Handling</a></h3> 1. Using catch_unwind in Async Context</a></h4> use std::panic::{catch_unwind, AssertUnwindSafe}; async fn handle_async_panic() -> Result<(), Box<dyn std::error::Error>> { let result = catch_unwind(AssertUnwindSafe(async { // Potentially panicking async code panic!("Async panic!"); })).await; match result { Ok(_) => Ok(()), Err(e) => { eprintln!("Caught panic: {:?}", e); Err("Async operation panicked".into()) } } } </code></pre> 2. Task-Level Panic Handling with Tokio</a></h4> use tokio::task::JoinHandle; async fn spawn_supervised_task() -> Result<(), Box<dyn std::error::Error>> { let handle: JoinHandle<Result<(), Error>> = tokio::spawn(async { // Your task code here Ok(()) }); match handle.await { Ok(Ok(_)) => Ok(()), Ok(Err(e)) => Err(e.into()), Err(e) if e.is_panic() => { eprintln!("Task panicked: {:?}", e); Err("Task panic".into()) } Err(e) => Err(e.into()), } } </code></pre> Custom Panic Hooks for Application-Wide Handling</a></h3> use std::panic; use log::{error, info}; fn setup_panic_hooks() { panic::set_hook(Box::new(|panic_info| { error!("Application panic occurred!"); error!("Panic info: {:?}", panic_info); // Optional: Send panic info to monitoring service send_to_monitoring(panic_info); // Optional: Initiate graceful shutdown initiate_shutdown(); })); } fn send_to_monitoring(panic_info: &panic::PanicInfo) { // Implementation for sending to monitoring service } fn initiate_shutdown() { // Implementation for graceful shutdown } </code></pre> Structured Panic Handling for Large Applications</a></h2> 1. Panic Recovery Middleware</a></h3> use std::future::Future; use std::pin::Pin; pub struct PanicRecoveryMiddleware<S> { inner: S, } impl<S> PanicRecoveryMiddleware<S> { pub fn new(inner: S) -> Self { Self { inner } } pub async fn handle_request<F, R>(&self, fut: F) -> Result<R, Error> where F: Future<Output = R> + Send + 'static, R: Send + 'static, { let result = tokio::spawn(async move { catch_unwind(AssertUnwindSafe(async move { fut.await })).await }).await??; Ok(result) } } </code></pre> 2. Supervisor Pattern for Long-Running Tasks</a></h3> pub struct TaskSupervisor { tasks: Vec<JoinHandle<()>>, shutdown_tx: broadcast::Sender<()>, } impl TaskSupervisor { pub fn new() -> Self { let (shutdown_tx, _) = broadcast::channel(1); Self { tasks: Vec::new(), shutdown_tx, } } pub fn spawn_supervised<F>(&mut self, task: F) where F: Future<Output = ()> + Send + 'static, { let mut shutdown_rx = self.shutdown_tx.subscribe(); let handle = tokio::spawn(async move { tokio::select! { _ = shutdown_rx.recv() => { info!("Task received shutdown signal"); } result = catch_unwind(AssertUnwindSafe(task)) => { if let Err(e) = result { error!("Task panicked: {:?}", e); } } } }); self.tasks.push(handle); } pub async fn shutdown(self) { let _ = self.shutdown_tx.send(()); for task in self.tasks { if let Err(e) = task.await { error!("Error shutting down task: {:?}", e); } } } } </code></pre> 3. Error Context and Reporting</a></h3> #[derive(Debug)] pub struct PanicContext { pub timestamp: DateTime<Utc>, pub thread: String, pub backtrace: Backtrace, pub message: String, } impl PanicContext { pub fn capture(panic_info: &panic::PanicInfo) -> Self { Self { timestamp: Utc::now(), thread: thread::current().name() .unwrap_or("unnamed") .to_string(), backtrace: Backtrace::capture(), message: panic_info.to_string(), } } pub async fn report(&self) { // Implementation for reporting panic context // Could send to logging service, monitoring system, etc. } } </code></pre> Best Practices for Panic Prevention</a></h2> 1. Defensive Programming</a></h3> fn defensive_array_access(arr: &[i32], index: usize) -> Option<i32> { arr.get(index).copied() } async fn process_data(data: &[i32]) -> Result<(), Error> { for i in 0..data.len() { if let Some(value) = defensive_array_access(data, i) { process_value(value).await?; } } Ok(()) } </code></pre> 2. Resource Cleanup with Drop</a></h3> struct DatabaseConnection { client: Client, } impl Drop for DatabaseConnection { fn drop(&mut self) { // Ensure resources are cleaned up even in case of panic if let Err(e) = self.client.close() { error!("Error closing database connection: {:?}", e); } } } </code></pre> 3. Structured Logging for Better Debugging</a></h3> use tracing::{info, error, instrument}; #[instrument] async fn critical_operation() -> Result<(), Error> { info!("Starting critical operation"); if let Err(e) = perform_operation().await { error!(error = ?e, "Critical operation failed"); return Err(e); } info!("Critical operation completed successfully"); Ok(()) } </code></pre> Testing Panic Handling</a></h2> 1. Unit Tests for Panic Recovery</a></h3> #[cfg(test)] mod tests { use super::*; #[tokio::test] async fn test_panic_recovery() { let result = catch_unwind(AssertUnwindSafe(async { panic!("Test panic"); })).await; assert!(result.is_err()); } } </code></pre> 2. Integration Tests</a></h3> #[tokio::test] async fn test_supervisor_recovery() { let mut supervisor = TaskSupervisor::new(); supervisor.spawn_supervised(async { panic!("Supervised task panic"); }); // Wait for some time tokio::time::sleep(Duration::from_secs(1)).await; // Verify supervisor state supervisor.shutdown().await; } </code></pre> Production Considerations</a></h2> 1. Memory Safety in Panic Situations</a></h3> struct SafeResource<T> { inner: Option<T>, } impl<T> SafeResource<T> { pub fn new(resource: T) -> Self { Self { inner: Some(resource) } } pub async fn use_resource<F, R>(&mut self, f: F) -> Result<R, Error> where F: FnOnce(&mut T) -> R, { let resource = self.inner.as_mut() .ok_or_else(|| Error::ResourceUnavailable)?; Ok(f(resource)) } } impl<T> Drop for SafeResource<T> { fn drop(&mut self) { if let Some(resource) = self.inner.take() { // Clean up resource } } } </code></pre> 2. Monitoring and Alerting</a></h3> async fn monitor_task_health( task_metrics: Arc<TaskMetrics>, alert_client: AlertClient, ) { loop { if task_metrics.panic_count.load(Ordering::Relaxed) > 0 { alert_client.send_alert( AlertLevel::Critical, "Task panic detected", ).await; } tokio::time::sleep(Duration::from_secs(60)).await; } } </code></pre> 3. Graceful Shutdown Implementation</a></h3> pub struct Application { supervisor: TaskSupervisor, shutdown_signal: broadcast::Receiver<()>, } impl Application { pub async fn run(mut self) -> Result<(), Error> { loop { tokio::select! { _ = self.shutdown_signal.recv() => { info!("Shutdown signal received"); break; } err = self.supervisor.check_tasks() => { if let Err(e) = err { error!("Task error: {:?}", e); break; } } } } self.supervisor.shutdown().await; Ok(()) } } </code></pre> Conclusion</a></h2> Proper panic handling in async Rust requires: Understanding different panic scenarios</li> Implementing appropriate recovery mechanisms</li> Using supervisor patterns for task management</li> Ensuring proper resource cleanup</li> Implementing monitoring and alerting</li> Testing panic handling thoroughly</li> Following best practices for prevention</li> </ol> Remember that while panic handling is important, it's better to design your code to avoid panics where possible, using Result and Option types for expected error cases. Send and Sync hazard 2024-07-04T00:00:00+00:00 Understanding Send and Sync Hazards in Rust: A Comprehensive Guide</a></h1> Introduction</a></h2> The Send</code> and Sync</code> traits play a crucial role in Rust's concurrency safety model. However, incorrect implementations or assumptions about these traits can lead to serious bugs and undefined behavior, especially in large async codebases. Foundation: Understanding Send and Sync</a></h2> pub unsafe auto trait Send {} pub unsafe auto trait Sync {} </code></pre> Basic Definitions</a></h3> // Send: Type can be safely transferred across thread boundaries trait Send {} // Sync: Type can be safely shared across thread boundaries trait Sync {} // Relationship: T: Sync implies &T: Send </code></pre> Common Hazards and Anti-patterns</a></h2> 1. Incorrect Manual Implementation of Send/Sync</a></h3> // DANGEROUS: Incorrect implementation struct UnsafeCounter { count: *mut i32, } // THIS IS UNSAFE AND INCORRECT unsafe impl Send for UnsafeCounter {} // WRONG! unsafe impl Sync for UnsafeCounter {} // WRONG! // The correct way would be: struct SafeCounter { count: Arc<AtomicI32>, } // This automatically implements Send and Sync safely </code></pre> 2. Interior Mutability Hazards</a></h3> use std::cell::Cell; use std::sync::Arc; // DANGEROUS: Cell is !Sync but wrapped in Arc struct SharedState { value: Arc<Cell<i32>>, // This is a trap! } impl SharedState { pub fn increment(&self) { // This is undefined behavior when shared across threads self.value.set(self.value.get() + 1); } } // SAFE: Using proper atomic types struct SafeSharedState { value: Arc<AtomicI32>, } impl SafeSharedState { pub fn increment(&self) { self.value.fetch_add(1, Ordering::SeqCst); } } </code></pre> 3. Async Context Hazards</a></h3> // DANGEROUS: Mixing async and sync code incorrectly struct AsyncProcessor { data: Arc<Mutex<Vec<String>>>, } impl AsyncProcessor { // HAZARD: Blocking in async context async fn process(&self) -> Result<(), Box<dyn Error>> { let mut data = self.data.lock().unwrap(); // Could block! // Process data Ok(()) } } // SAFE: Using async-aware primitives struct SafeAsyncProcessor { data: Arc<Tokio::sync::Mutex<Vec<String>>>, } impl SafeAsyncProcessor { async fn process(&self) -> Result<(), Box<dyn Error>> { let mut data = self.data.lock().await; // Process data Ok(()) } } </code></pre> Complex Hazards in Large Systems</a></h2> 1. Hidden Sync Requirements</a></h3> struct ComplexSystem { cache: Arc<Cache>, processor: Arc<DataProcessor>, notifier: Arc<EventNotifier>, } // DANGEROUS: Hidden non-Send type struct Cache { entries: HashMap<String, Rc<CacheEntry>>, // Rc is !Send _phantom: PhantomData<*const ()>, // !Send and !Sync } // SAFE: Explicit Send/Sync bounds struct SafeCache { entries: Arc<DashMap<String, Arc<CacheEntry>>>, } </code></pre> 2. Callback Hell with Send/Sync Issues</a></h3> // DANGEROUS: Callbacks with unclear Send/Sync requirements struct EventSystem { callbacks: Vec<Box<dyn Fn() + Send + 'static>>, unsafe_callbacks: Vec<Box<dyn Fn()>>, // Missing Send bound! } // SAFE: Explicit bounds and type-safe callbacks struct SafeEventSystem<F> where F: Fn() + Send + Sync + 'static, { callbacks: Vec<F>, } </code></pre> 3. Resource Management Hazards</a></h3> // DANGEROUS: Resource cleanup with Send/Sync issues struct ResourceManager { resources: Arc<Mutex<Vec<Resource>>>, cleanup_callbacks: Vec<Box<dyn FnMut() + Send>>, } impl ResourceManager { // HAZARD: Cleanup in destructor could panic or deadlock fn cleanup(&mut self) { let resources = self.resources.lock().unwrap(); for callback in &mut self.cleanup_callbacks { callback(); // Could panic or deadlock! } } } // SAFE: Structured resource management struct SafeResourceManager { resources: Arc<Tokio::sync::Mutex<Vec<Resource>>>, cleanup_callbacks: Arc<Tokio::sync::Mutex<Vec<Box<dyn FnMut() + Send + Sync>>>>, } impl SafeResourceManager { async fn cleanup(&mut self) { let mut resources = self.resources.lock().await; let mut callbacks = self.cleanup_callbacks.lock().await; for callback in callbacks.iter_mut() { // Handle cleanup errors gracefully if let Err(e) = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { callback(); })) { log::error!("Cleanup callback panicked: {:?}", e); } } } } </code></pre> Thread Pool and Executor Hazards</a></h2> 1. Executor State Sharing</a></h3> // DANGEROUS: Incorrect executor state sharing struct AsyncExecutor { state: Arc<Mutex<ExecutorState>>, runtime: tokio::runtime::Runtime, } struct ExecutorState { tasks: Vec<Box<dyn Future<Output = ()> + Send>>, callbacks: Vec<Box<dyn Fn() + Send>>, } // HAZARD: Could deadlock or cause undefined behavior impl AsyncExecutor { async fn execute(&self) { let state = self.state.lock().unwrap(); for task in &state.tasks { self.runtime.spawn(task); // Could deadlock! } } } // SAFE: Proper async-aware state management struct SafeAsyncExecutor { state: Arc<Tokio::sync::Mutex<ExecutorState>>, runtime: tokio::runtime::Runtime, } impl SafeAsyncExecutor { async fn execute(&self) { let mut state = self.state.lock().await; for task in state.tasks.drain(..) { self.runtime.spawn(task); } } } </code></pre> 2. Task Cancellation Hazards</a></h3> // DANGEROUS: Incorrect task cancellation struct TaskManager { tasks: Arc<Mutex<HashMap<TaskId, JoinHandle<()>>>>, } impl TaskManager { // HAZARD: Deadlock potential during cleanup fn cancel_all(&self) { let tasks = self.tasks.lock().unwrap(); for (_, handle) in tasks.iter() { handle.abort(); // Could deadlock if task holds locks! } } } // SAFE: Graceful task cancellation struct SafeTaskManager { tasks: Arc<Tokio::sync::Mutex<HashMap<TaskId, JoinHandle<()>>>>, shutdown_signal: broadcast::Sender<()>, } impl SafeTaskManager { async fn cancel_all(&self) { // Signal all tasks to shut down let _ = self.shutdown_signal.send(()); // Wait for tasks with timeout let mut tasks = self.tasks.lock().await; for (_, handle) in tasks.drain() { tokio::select! { _ = handle => {}, _ = tokio::time::sleep(Duration::from_secs(5)) => { handle.abort(); } } } } } </code></pre> Best Practices and Mitigation Strategies</a></h2> 1. Type-Level Safety Guards</a></h3> use std::marker::PhantomData; // Enforce Send/Sync at type level struct ThreadSafeWrapper<T: Send + Sync> { inner: T, _marker: PhantomData<*const ()>, } impl<T: Send + Sync> ThreadSafeWrapper<T> { fn new(inner: T) -> Self { Self { inner, _marker: PhantomData, } } } </code></pre> 2. Compile-Time Verification</a></h3> #[cfg(test)] mod tests { use static_assertions::{assert_impl_all, assert_not_impl_any}; // Verify type safety at compile time assert_impl_all!(SafeType: Send, Sync); assert_not_impl_any!(UnsafeType: Send, Sync); } </code></pre> 3. Runtime Checks</a></h3> use std::any::Any; fn verify_send_sync<T: Send + Sync + Any>() { println!("Type {} is Send + Sync", std::any::type_name::<T>()); } #[test] fn verify_types() { verify_send_sync::<SafeType>(); // verify_send_sync::<UnsafeType>(); // Won't compile } </code></pre> Debugging and Analyzing Send/Sync Issues</a></h2> 1. Static Analysis Tools</a></h3> #[derive(Debug)] struct DataStructure { #[allow(dead_code)] data: Vec<String>, } // Use clippy to catch potential issues #[warn(clippy::missing_safety_doc)] unsafe impl Send for DataStructure {} // Clippy will warn about missing safety documentation </code></pre> 2. Runtime Diagnostics</a></h3> use tracing::{info, error, warn}; async fn monitor_thread_safety<T: Send + Sync>(value: T) { let type_name = std::any::type_name::<T>(); info!("Monitoring thread safety for type: {}", type_name); if std::mem::size_of::<T>() > 512 { warn!("Large type may cause performance issues when sent between threads"); } // Monitor for potential issues tokio::spawn(async move { if let Err(e) = process_value(value).await { error!("Thread safety violation: {:?}", e); } }); } </code></pre> Conclusion</a></h2> When working with Send and Sync traits in large async Rust codebases: Always Consider Thread Safety Verify Send/Sync implementations</li> Use appropriate synchronization primitives</li> Consider async-aware alternatives</li> </ul> </li> Design for Safety Use type-level guarantees</li> Implement proper resource cleanup</li> Handle task cancellation gracefully</li> </ul> </li> Monitor and Debug Use static analysis tools</li> Implement runtime diagnostics</li> Test thoroughly for concurrency issues</li> </ul> </li> Follow Best Practices Use async-aware primitives</li> Implement proper error handling</li> Consider performance implications</li> </ul> </li> Documentation Document thread safety requirements</li> Explain synchronization strategies</li> Detail potential hazards</li> </ul> </li> </ol> Remember that incorrect Send/Sync implementations can lead to subtle and dangerous bugs. Always err on the side of caution and thoroughly test concurrent code. Understanding stream in rust 2024-07-03T00:00:00+00:00 Comprehensive Guide to Futures::Stream in Rust</a></h1> Introduction</a></h2> futures::Str } </code></pre> } } </code></pre> } } } } </code></pre> } } } } } } } } } </code></pre> } } } } } } } } } </code></pre> } } } } } } } </code></pre> } } } } } )) } } } </code></pre> } { }))) } } } } </code></pre> } { } } } } } } } </code></pre> } } } } } </code></pre> } } } } } } </code></pre> } } } </code></pre> } } } } } } </code></pre> } } } } } } } )) } } </code></pre> Asynchronous Natural Efficient Support for back-pressure</li> </ul> </li> Composa Easy Rich set of combinators</li> Integration </ul> </li> Memory Lazy evaluation</li> Controlled buffering</li> Stream </ul> </li> </ol> Complex More Pin requirements</li> Error handling complexity</li> </ul> </li> Runtime Task scheduling overhead</li> Memory Context switching costs</li> </ul> </li> Learning Understanding Dealing with lifetimes</li> Managing pinning</li> </ul> </li> </ol> futures:: Efficient Rich Good </ul> However, Implementation complexity</li> Memory management</li> Error handling strategies</li> Performance implications</li> </ul> The key Remember to: Profile Test Consider Handle Optimize </ul> This comprehensive Don't block just flow 2024-03-02T00:00:00+00:00 eam</code> is a fundamental abstraction in asynchronous Rust programming that represents a sequence of asynchronous values. This guide explores its design, implementation patterns, and practical considerations. class="zola-anchor" href="#basic-concepts" aria-label="Anchor link for: basic-concepts">Basic Concepts</a></h2> it-definition">Stream Trait Definition</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">pub trait Stream { type Item; fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>>; ences-from-iterator">Key Differences from Iterator</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">// Iterator (synchronous) style="color:#fa6e32;">trait Iterator { type Item; fn next(&mut self) -> Option<Self::Item>; style="font-style:italic;color:#abb0b6;">// Stream (asynchronous) style="color:#fa6e32;">trait Stream { type Item; fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>; tion-patterns">Implementation Patterns</a></h2> ream-implementation">1. Basic Stream Implementation</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">use futures::{Stream, StreamExt}; style="color:#fa6e32;">use std::pin::Pin; style="color:#fa6e32;">use std::task::{Context, Poll}; style="color:#fa6e32;">struct CounterStream { current: u64, max: u64, style="color:#fa6e32;">impl Stream for CounterStream { type Item = u64; fn poll_next( mut self: Pin<&mut Self>, _cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { if self.current >= self.max { return Poll::Ready(None); let result = self.current; self.current += 1; Poll::Ready(Some(result)) -stream-implementation">2. Buffered Stream Implementation</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">use std::collections::VecDeque; style="color:#fa6e32;">struct BufferedStream<T> { buffer: VecDeque<T>, source: Box<dyn Stream<Item = T> + Unpin>, capacity: usize, style="color:#fa6e32;">impl<T> BufferedStream<T> { fn new(source: impl Stream<Item = T> + Unpin + 'static, capacity: usize) -> Self { Self { buffer: VecDeque::with_capacity(capacity), source: Box::new(source), capacity, style="color:#fa6e32;">impl<T> Stream for BufferedStream<T> { type Item = T; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { // Try to fill buffer while self.buffer.len() < self.capacity { match Pin::new(&mut self.source).poll_next(cx) { Poll::Ready(Some(item)) => self.buffer.push_back(item), Poll::Ready(None) => break, Poll::Pending => break, // Return item from buffer if available if let Some(item) = self.buffer.pop_front() { Poll::Ready(Some(item)) } else if self.buffer.is_empty() { Pin::new(&mut self.source).poll_next(cx) } else { Poll::Pending tream-patterns">Advanced Stream Patterns</a></h2> ssure-implementation">1. Back-Pressure Implementation</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct BackPressuredStream<T> { inner: Pin<Box<dyn Stream<Item = T>>>, high_watermark: usize, current_pressure: usize, style="color:#fa6e32;">impl<T> BackPressuredStream<T> { fn new( inner: impl Stream<Item = T> + 'static, high_watermark: usize ) -> Self { Self { inner: Box::pin(inner), high_watermark, current_pressure: 0, style="color:#fa6e32;">impl<T> Stream for BackPressuredStream<T> { type Item = T; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { if self.current_pressure >= self.high_watermark { return Poll::Pending; match self.inner.as_mut().poll_next(cx) { Poll::Ready(Some(item)) => { self.current_pressure += 1; Poll::Ready(Some(item)) other => other, ited-stream">2. Rate-Limited Stream</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">use tokio::time::{Duration, Instant}; style="color:#fa6e32;">struct RateLimitedStream<S> { inner: S, rate: Duration, last_emit: Option<Instant>, style="color:#fa6e32;">impl<S: Stream> Stream for RateLimitedStream<S> { type Item = S::Item; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { let now = Instant::now(); if let Some(last_emit) = self.last_emit { let elapsed = now - last_emit; if elapsed < self.rate { // Not enough time has passed cx.waker().wake_by_ref(); return Poll::Pending; match unsafe { Pin::new_unchecked(&mut self.inner) }.poll_next(cx) { Poll::Ready(Some(item)) => { self.last_emit = Some(now); Poll::Ready(Some(item)) other => other, e-considerations">Performance Considerations</a></h2> class="zola-anchor" href="#1-memory-management" aria-label="Anchor link for: 1-memory-management">1. Memory Management</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct ChunkedStream<S: Stream> { inner: S, chunk_size: usize, current_chunk: Vec<S::Item>, style="color:#fa6e32;">impl<S: Stream> Stream for ChunkedStream<S> { type Item = Vec<S::Item>; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { while self.current_chunk.len() < self.chunk_size { match unsafe { Pin::new_unchecked(&mut self.inner) }.poll_next(cx) { Poll::Ready(Some(item)) => { self.current_chunk.push(item); Poll::Ready(None) if !self.current_chunk.is_empty() => { return Poll::Ready(Some( std::mem::replace(&mut self.current_chunk, Vec::new()) )); Poll::Ready(None) => return Poll::Ready(None), Poll::Pending => return Poll::Pending, if self.current_chunk.len() == self.chunk_size { Poll::Ready(Some( std::mem::replace(&mut self.current_chunk, Vec::with_capacity(self.chunk_size)) } else { Poll::Pending d-operations">2. CPU-Bound Operations</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct ComputeBoundStream<S, F> { inner: S, transform: F, runtime_handle: tokio::runtime::Handle, style="color:#fa6e32;">impl<S, F, T, U> Stream for ComputeBoundStream<S, F> style="color:#fa6e32;">where S: Stream<Item = T> + Unpin, F: Fn(T) -> U + Send + 'static, T: Send + 'static, U: Send + 'static, type Item = U; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { match Pin::new(&mut self.inner).poll_next(cx) { Poll::Ready(Some(item)) => { let transform = self.transform.clone(); let handle = self.runtime_handle.clone(); Poll::Ready(Some(handle.block_on(async move { tokio::task::spawn_blocking(move || transform(item)).await.unwrap() Poll::Ready(None) => Poll::Ready(None), Poll::Pending => Poll::Pending, class="zola-anchor" href="#error-handling" aria-label="Anchor link for: error-handling">Error Handling</a></h2> ble-errors">1. Recoverable Errors</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct RetryStream<S> { inner: S, retry_count: usize, max_retries: usize, style="color:#fa6e32;">impl<S, T, E> Stream for RetryStream<S> style="color:#fa6e32;">where S: Stream<Item = Result<T, E>> + Unpin, E: std::error::Error, type Item = Result<T, E>; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { loop { match Pin::new(&mut self.inner).poll_next(cx) { Poll::Ready(Some(Ok(item))) => { self.retry_count = 0; return Poll::Ready(Some(Ok(item))); Poll::Ready(Some(Err(e))) => { if self.retry_count < self.max_retries { self.retry_count += 1; continue; return Poll::Ready(Some(Err(e))); other => return other, rable-errors">2. Unrecoverable Errors</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct FallibleStream<S> { inner: S, error_handler: Box<dyn Fn(Box<dyn std::error::Error>) + Send>, style="color:#fa6e32;">impl<S: Stream> Stream for FallibleStream<S> { type Item = S::Item; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { match unsafe { Pin::new_unchecked(&mut self.inner) }.poll_next(cx) { Poll::Ready(Some(item)) => Poll::Ready(Some(item)), Poll::Ready(None) => Poll::Ready(None), Poll::Pending => { // Handle potential errors during pending state Poll::Pending class="zola-anchor" href="#testing-strategies" aria-label="Anchor link for: testing-strategies">Testing Strategies</a></h2> class="zola-anchor" href="#1-mock-streams" aria-label="Anchor link for: 1-mock-streams">1. Mock Streams</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">#[cfg(test)] style="color:#fa6e32;">mod tests { use super::*; use futures::stream; use std::time::Duration; struct MockStream<T> { items: Vec<T>, delay: Duration, impl<T: Clone> Stream for MockStream<T> { type Item = T; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { if self.items.is_empty() { Poll::Ready(None) } else { tokio::time::sleep(self.delay).await; Poll::Ready(Some(self.items.remove(0))) #[tokio::test] async fn test_stream_behavior() { let mock = MockStream { items: vec![1, 2, 3], delay: Duration::from_millis(100), }; let mut stream = BufferedStream::new(mock, 2); assert_eq!(stream.next().await, Some(1)); assert_eq!(stream.next().await, Some(2)); assert_eq!(stream.next().await, Some(3)); assert_eq!(stream.next().await, None); -based-testing">2. Property-Based Testing</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">#[cfg(test)] style="color:#fa6e32;">mod tests { use proptest::prelude::*; proptest! { #[test] fn test_stream_properties(inputs: Vec<i32>) { let stream = stream::iter(inputs.clone()); let buffered = BufferedStream::new(stream, 10); tokio_test::block_on(async { let collected: Vec<_> = buffered.collect().await; prop_assert_eq!(inputs, collected); }); ices-and-optimizations">Best Practices and Optimizations</a></h2> class="zola-anchor" href="#1-stream-fusion" aria-label="Anchor link for: 1-stream-fusion">1. Stream Fusion</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct FusedStream<S> { inner: S, is_terminated: bool, style="color:#fa6e32;">impl<S: Stream> Stream for FusedStream<S> { type Item = S::Item; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { if self.is_terminated { return Poll::Ready(None); match unsafe { Pin::new_unchecked(&mut self.inner) }.poll_next(cx) { Poll::Ready(None) => { self.is_terminated = true; Poll::Ready(None) other => other, class="zola-anchor" href="#2-batch-processing" aria-label="Anchor link for: 2-batch-processing">2. Batch Processing</a></h3> style="background-color:#fafafa;color:#61676c;" class="language-rust ">struct BatchProcessor<S> { inner: S, batch_size: usize, current_batch: Vec<S::Item>, style="color:#fa6e32;">impl<S: Stream> Stream for BatchProcessor<S> { type Item = Vec<S::Item>; fn poll_next( mut self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>> { while self.current_batch.len() < self.batch_size { match unsafe { Pin::new_unchecked(&mut self.inner) }.poll_next(cx) { Poll::Ready(Some(item)) => { self.current_batch.push(item); Poll::Ready(None) if !self.current_batch.is_empty() => { return Poll::Ready(Some( std::mem::replace(&mut self.current_batch, Vec::new()) )); Poll::Ready(None) => return Poll::Ready(None), Poll::Pending => { if !self.current_batch.is_empty() { return Poll::Ready(Some( std::mem::replace(&mut self.current_batch, Vec::new()) )); return Poll::Pending; Poll::Ready(Some( std::mem::replace(&mut self.current_batch, Vec::with_capacity(self.batch_size)) class="zola-anchor" href="#pros-and-cons" aria-label="Anchor link for: pros-and-cons">Pros and Cons</a></h2> class="zola-anchor" href="#pros" aria-label="Anchor link for: pros">Pros:</a></h3> Processing fit for I/O-bound operations</li> resource utilization</li> bility to chain transformations</li> with async/await</li> Efficiency fusion opportunities</li> class="zola-anchor" href="#cons" aria-label="Anchor link for: cons">Cons:</a></h3> ity complex than Iterator</li> Overhead allocation for futures</li> Curve async concepts</li> class="zola-anchor" href="#conclusion" aria-label="Anchor link for: conclusion">Conclusion</a></h2> Stream</code> is a powerful abstraction for async programming in Rust, offering: handling of asynchronous sequences</li> composition capabilities</li> performance characteristics</li> it requires careful consideration of: to successful usage is understanding these trade-offs and choosing appropriate patterns for your specific use case. your stream implementations</li> edge cases thoroughly</li> backpressure mechanisms</li> errors appropriately</li> for your specific use case</li> overview shoul I gave a talk titled "Don't Block, Just Flow: Embracing Asynchronous with Rust Streams." It focused on using futures::stream::Stream in Rust. The talk covered the importance of I/O concurrency for all applications, pinning and boxing of dynamic types, the relationship between Send and Sync with streams, and backpressure handling. In general, it explored how futures::stream::Stream is used, the practical utilities it offers for applications, and the issues it helps address. For those interested in learning more, you can find resources here: </a>

artech

Dealing with Panics 🔥 in async rust 🦀

Async Runtime and Panic Handling Strategy</a></h1> If you are writing async Rust, then you have to choose an async executor which will run your futures/async tasks forward. Below is a list of some widely adopted and often used executors:</p> tokio</li> async-std</li>

AsRef vs Borrow vs Deref Busted

Understanding panic handling in larger codebase

Send and Sync hazard

Understanding stream in rust

Asynchronous

Complex

futures:: Efficient Rich Good </ul> However, Implementation complexity</li> Memory management</li> Error handling strategies</li> Performance implications</li> </ul> The key Remember to:</p> Profile Test Consider Handle Optimize </ul> This comprehensive

Don't block just flow

`futures:: Efficient Rich Good </ul> However, Implementation complexity</li> Memory management</li> Error handling strategies</li> Performance implications</li> </ul> The key Remember to:</p> Profile Test Consider Handle Optimize </ul> This comprehensive`