From caab57586a6e5e9201c265c47c9dcf886499cb45 Mon Sep 17 00:00:00 2001 From: Jeff Olson Date: Fri, 27 Apr 2012 22:19:20 -0700 Subject: rt/std: whitespace cleanup + work on hl/global_loop docs --- src/libstd/uv_global_loop.rs | 3 +-- src/libstd/uv_hl.rs | 61 ++++++++++++++++++++++++++++---------------- 2 files changed, 40 insertions(+), 24 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/uv_global_loop.rs b/src/libstd/uv_global_loop.rs index 46d73867285..c280a184cef 100644 --- a/src/libstd/uv_global_loop.rs +++ b/src/libstd/uv_global_loop.rs @@ -28,7 +28,6 @@ fn get() -> hl::high_level_loop { ret get_monitor_task_gl(); } -// WARNING: USE ONLY ONE get_*_task_gl fn in the scope of a process lifetime. #[doc(hidden)] fn get_monitor_task_gl() -> hl::high_level_loop { let monitor_loop_chan_ptr = @@ -100,7 +99,7 @@ unsafe fn spawn_libuv_weak_task() -> (*ll::uv_async_t, let exit_po = comm::port::<(*ll::uv_async_t, comm::chan)>(); let exit_ch = comm::chan(exit_po); - + task::spawn_sched(task::manual_threads(1u)) {|| log(debug, "entering global libuv task"); let loop_ptr = ll::loop_new(); diff --git a/src/libstd/uv_hl.rs b/src/libstd/uv_hl.rs index 75c5c6ebea4..83080348d0b 100644 --- a/src/libstd/uv_hl.rs +++ b/src/libstd/uv_hl.rs @@ -13,16 +13,12 @@ import ll = uv_ll; #[doc = " Used to abstract-away direct interaction with a libuv loop. - -# Arguments - -* async_handle - a pointer to a pointer to a uv_async_t struct used to 'poke' -the C uv loop to process any pending callbacks - -* op_chan - a channel used to send function callbacks to be processed -by the C uv loop "] enum high_level_loop { + #[doc=" + `high_level_loop` variant that carries a `comm::chan` and + a `*ll::uv_async_t`. + "] simple_task_loop({ async_handle: *ll::uv_async_t, op_chan: comm::chan @@ -34,23 +30,36 @@ Represents the range of interactions with a `high_level_loop` "] enum high_level_msg { interaction (fn~(*libc::c_void)), + #[doc=" +For use in libraries that roll their own `high_level_loop` (like +`std::uv::global_loop`) + +Is used to signal to the loop that it should close the internally-held +async handle and do a sanity check to make sure that all other handles are +closed, causing a failure otherwise. This should not be sent/used from +'normal' user code. + "] teardown_loop } #[doc = " -Given a vanilla `uv_loop_t*` +Useful for anyone who wants to roll their own `high_level_loop`. # Arguments * loop_ptr - a pointer to a currently unused libuv loop. Its `data` field will be overwritten before the loop begins -must be a pointer to a clean rust `uv_async_t` record -* msg_po - an active port that receives `high_level_msg`s -* before_run - a unique closure that is invoked after `uv_async_init` is -called on the `async_handle` passed into this callback, just before `uv_run` -is called on the provided `loop_ptr` -* before_msg_drain - a unique closure that is invoked every time the loop is -awoken, but before the port pointed to in the `msg_po` argument is drained +* msg_po - an active port that receives `high_level_msg`s. You can distribute +a paired channel to users, along with the `async_handle` returned in the +following callback (combine them to make a `hl::simpler_task_loop` varient +of `hl::high_level_loop`) +* before_run - a unique closure that is invoked before `uv_run()` is called +on the provided `loop_ptr`. An `async_handle` is passed in which will be +live for the duration of the loop. You can distribute this to users so that +they can interact with the loop safely. +* before_msg_process - a unique closure that is invoked at least once when +the loop is woken up, and once more for every message that is drained from +the loop's msg port * before_tear_down - called just before the loop invokes `uv_close()` on the provided `async_handle`. `uv_run` should return shortly after "] @@ -93,17 +102,25 @@ Provide a callback to be processed by `a_loop` The primary way to do operations again a running `high_level_loop` that doesn't involve creating a uv handle via `safe_handle` +# Warning + +This function is the only safe way to interact with _any_ `high_level_loop`. +Using functions in the `uv::ll` module outside of the `cb` passed into +this function is _very dangerous_. + # Arguments -* a_loop - a `high_level_loop` that you want to do operations against +* hl_loop - a `uv::hl::high_level_loop` that you want to do operations against * cb - a function callback to be processed on the running loop's -thread. The only parameter is an opaque pointer to the running -uv_loop_t. In the context of this callback, it is safe to use this pointer -to do various uv_* API calls. _DO NOT_ send this pointer out via ports/chans +thread. The only parameter passed in is an opaque pointer representing the +running `uv_loop_t*`. In the context of this callback, it is safe to use +this pointer to do various uv_* API calls contained within the `uv::ll` +module. It is not safe to send the `loop_ptr` param to this callback out +via ports/chans. "] -unsafe fn interact(a_loop: high_level_loop, +unsafe fn interact(hl_loop: high_level_loop, -cb: fn~(*libc::c_void)) { - send_high_level_msg(a_loop, interaction(cb)); + send_high_level_msg(hl_loop, interaction(cb)); } // INTERNAL API -- cgit 1.4.1-3-g733a5