{"id":4506,"date":"2018-11-29T17:55:03","date_gmt":"2018-11-29T23:55:03","guid":{"rendered":"http:\/\/neosmart.net\/blog\/?p=4506"},"modified":"2018-12-04T12:11:38","modified_gmt":"2018-12-04T18:11:38","slug":"rsevents-manual-and-auto-reset-events-for-rust","status":"publish","type":"post","link":"https:\/\/neosmart.net\/blog\/rsevents-manual-and-auto-reset-events-for-rust\/","title":{"rendered":"rsevents: manual and auto reset events for rust"},"content":{"rendered":"

\"\"<\/a>One of the unique characteristics of Rust (both the language and the community that has evolved around it) is a strong acknowledgement of multithreading, synchronization, and concurrency, as witnessed in the design of the core language (which acknowledges OS concepts of threads with sync<\/code>\u00a0and send<\/code>) and the presence of various structures in the standard library aimed at simplifying development of correct, multithreaded code.<\/p>\n

rsevents<\/a><\/code>\u00a0is a new crate that should be immediately familiar to anyone that has done multithreaded programming under Windows: it exposes a synchronization primitive<\/em>, namely, an event<\/code>\u00a0for use where Mutex<\/code>\u00a0– intended to exclusively marshall access to a variable or region of code – either does not convey the correct semantics or is not the right tool for the job. For those that didn’t come fleeing to rust from a Win32 background, in Windows an event<\/code>\u00a0is the lowest-level kernel synchronization primitive, which can be thought of as a “waitable bool<\/code>” – it is either set<\/code>\u00a0or reset<\/code>\u00a0(on or off, true or false) and if it isn’t set, you can wait on it until it becomes set.<\/p>\n

<\/p>\n

An event is used for (unstructured) synchronization of state, a lot like an anonymous, 1-bit\u00a0Channel<\/code>\u00a0but simultaneously much more flexible (but trickier!) as it is a primitive. To naively implement events in rust (or in posix<\/a>), it would be the equivalent of a conditional variable and a mutex, where the mutex is used only to protect the integrity of the conditional variable (and not to otherwise indicate a critical section), only without spurious wakes. Win32 events (and rsevents<\/code>) come in two different variants, a so-called “manual reset” event and the (undoubtedly more important) “auto reset” event. To continue with the posix parallel, the behavior is the difference between using pthread_cond_broadcast<\/code> and pthread_cond_signal<\/code>\u00a0– it either wakes up all waiting listeners or only one, thereby guaranteeing atomicity.<\/p>\n

rsevents<\/code>\u00a0implements these as rsevents::AutoResetEvent<\/a><\/code>\u00a0and rsevents::ManualResetEvent<\/code><\/a>, both impl<\/code>s of the trait rsevents::Awaitable<\/a><\/code>, atop of the excellent ParkingLot<\/code>\u00a0crate for the best sleep\/wake performance rust currently has to offer, with minimal overhead to boot. As the docs illustrate<\/a>, they are dead-simple to use and allow one to quickly get started with easily polling or awaiting state changes:<\/p>\n

\/\/ create a new, initially unset event\r\nlet event = AutoResetEvent::new(State::Unset);\r\n\r\n\/\/ and wrap it in an ARC to allow sharing across thread boundaries\r\nlet event = Arc::new(event);\r\n\r\n\/\/ create a worker thread to complete some task\r\n{\r\n\tlet shared = event.clone();\r\n\tstd::thread::spawn(|| {\r\n\t\t\/\/ perform some task\r\n\t\t...\r\n\t\t\/\/ and signal to ONE waiting thread that the result is ready\r\n\t\tshared.set();\r\n\t});\r\n}\r\n\r\n...\r\n\r\n\/\/ wait for the spawned thread to finish the queued work\r\nevent.wait();\r\n<\/code><\/pre>\n
rsevents<\/code>\u00a0only represents the core underpinnings of event-based synchronization – as mentioned repeatedly, these are\u00a0synchronization primitives<\/em> and while they may be useful on their own to communicate changes in (one-bit) state,1<\/a><\/sup> they are actually more useful to create Awaitable<\/code>\u00a0objects (hence the separation between the events and the Awaitable<\/code>\u00a0interface). This is where the true power of rsevents<\/code>\u00a0is exposed: it lets you build (or return) objects on top of the events, which become asynchronously awaitable.2<\/a><\/sup><\/p>\n
To get the ball rolling, a separate crate is also being introducing: rsevents-extra<\/code>\u00a0which contains helpful synchronization objects built atop of rsevents<\/code>\u00a0all of which implement rsevents::Awaitable<\/code>. One example of an object implementing such behavior is CountdownEvent<\/a><\/code>\u00a0which implements an awaitable reverse counter that can be used to wait until\u00a0n<\/em> tasks have finished: you initialize it some value, decrement it (calling CountdownEvent::tick()<\/code>) until it reaches zero, at which point any threads waiting on the object (via CountdownEvent::wait()<\/code>, courtesy of rsevents::Awaitable<\/code>) are awoken:<\/p>\n
let countdown = CountdownEvent::new(42);\r\n\r\nthread::scope(|scope| {\r\n    let worker_thread = scope.spawn(|_| {\r\n        println!(\"Worker thread reporting for duty!\");\r\n\r\n        \/\/ block here until all the countdown has elapsed\r\n        countdown.wait();\r\n\r\n        println!(\"Worker thread can now do something because the countdown finished!\");\r\n    });\r\n\r\n    for i in 0..1000 {\r\n        if i % 7 == 3 {\r\n            countdown.tick();\r\n        }\r\n    }\r\n});\r\n\r\n<\/code><\/pre>\n
It’s a pretty silly example that doesn’t do the crate justice, but countdown events are a great way of performantly waiting for an external event predicated on n<\/em> things taking place, and will outperform other alternatives that involve mutating shared state, while simultaneously abstracting away the process of actually waiting<\/em> on the state to change.<\/p>\n
In my days of Win32 C\/C++ programming, I had written an entire library of single-file headers each implementing a different synchronization model and built directly atop of auto or manual reset events. Rust has obviated quite a few of them, but there’s a lot to be said for the flexibility that events have to offer (and their very favorable performance characteristics). rsevents-extra<\/code>\u00a0is intended to be a community project and is accepting pull requests<\/a> for other useful synchronization objects implementing Awaitable<\/code>, so if you have any good ideas, we’re listening!<\/p>\n
  1. or to even implement crude critical sections, if you were mad enough ↩<\/a><\/p><\/li>
  2. Not to be confused with async<\/code>\/await<\/code>\u00a0which does the same but only as part of what is basically an event loop ↩<\/a><\/p><\/li><\/ol>","protected":false},"excerpt":{"rendered":"
    One of the unique characteristics of Rust (both the language and the community that has evolved around it) is a strong acknowledgement of multithreading, synchronization, and concurrency, as witnessed in the design of the core language (which acknowledges OS concepts … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":505,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[1],"tags":[989,52,11,993,936],"class_list":["post-4506","post","type-post","status-publish","format-standard","hentry","category-software","tag-crate","tag-open-source","tag-programming","tag-rsevents","tag-rust"],"aioseo_notices":[],"jetpack_featured_media_url":"","jetpack_shortlink":"https:\/\/wp.me\/p4xDa-1aG","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/posts\/4506","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/users\/505"}],"replies":[{"embeddable":true,"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/comments?post=4506"}],"version-history":[{"count":8,"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/posts\/4506\/revisions"}],"predecessor-version":[{"id":4514,"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/posts\/4506\/revisions\/4514"}],"wp:attachment":[{"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/media?parent=4506"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/categories?post=4506"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/neosmart.net\/blog\/wp-json\/wp\/v2\/tags?post=4506"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}