From 636526d6f1e243862dda6c9fafefc3cc1e9ca6fa Mon Sep 17 00:00:00 2001 From: Kevin Tew Date: Wed, 3 Mar 2010 21:42:24 +0000 Subject: [PATCH] Places docs edits svn: r18455 --- collects/scribblings/places/places.scrbl | 30 +++++++++++++----------- src/mzscheme/src/places.c | 14 +++++------ 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/collects/scribblings/places/places.scrbl b/collects/scribblings/places/places.scrbl index 7c518458e1..e94ca7c600 100644 --- a/collects/scribblings/places/places.scrbl +++ b/collects/scribblings/places/places.scrbl @@ -20,10 +20,12 @@ hardware threads. @defmodule[scheme/place]{} -@defproc[(place [module-path module-path?] [start-proc proc?] [place-channel place-ch?]) place?]{ +@defproc[(place [module-path module-path?] [start-proc proc?] [place-channel place-channel?]) place?]{ Starts running @scheme[start-proc] in parallel. scheme[start-proc] must - be a function defined in @scheme[module-path]. The @scheme[place] - procedure returns immediately with a place descriptor value. + be a function defined in @scheme[module-path]. Each place is created with a scheme[place-channel] + that permits communication with the place originator. This initial channel can be overridden with + an optional scheme[place-channel] argument. The @scheme[place] + procedure returns immediately with a place descriptor value representing the newly constructed place. } @defproc[(place-wait [p place?]) exact-integer?]{ @@ -32,19 +34,19 @@ hardware threads. } @defproc[(place? [x any/c]) boolean?]{ - Returns @scheme[#t] if @scheme[x] is a place. + Returns @scheme[#t] if @scheme[x] is a place object. } -@defproc[(place-ch-send [ch place-ch?] [x any/c]) void]{ +@defproc[(place-channel-send [ch place-channel?] [x any/c]) void]{ Sends an immutable message @scheme[x] on channel @scheme[ch]. } -@defproc[(place-ch-recv [p place-ch?]) any/c]{ +@defproc[(place-channel-recv [p place-channel?]) any/c]{ Returns an immutable message received on channel @scheme[ch]. } -@defproc[(place-ch? [x any/c]) boolean?]{ - Returns @scheme[#t] if @scheme[x] is a place-ch. +@defproc[(place-channel? [x any/c]) boolean?]{ + Returns @scheme[#t] if @scheme[x] is a place-channel object. } @section[#:tag "example"]{How Do I Keep Those Cores Busy?} @@ -53,15 +55,15 @@ This code launches two places passing 1 and 2 as the initial channels and then waits for the places to complete and return. @schemeblock[ - (let ((pls (map (lambda (x) (place "place_worker.ss" 'place-main x)) + (let ((pls (map (lambda (x) (place "place-worker.ss" 'place-main x)) (list 1 2)))) (map place-wait pls)) ] -This is the code for the place_worker.ss module that each place will execute. +This is the code for the place-worker.ss module that each place will execute. @schemeblock[ -(module place_worker scheme +(module place-worker scheme (provide place-main) (define (place-main x) @@ -76,9 +78,9 @@ Places can only communicate by passing immutable messages on place-channels. @section[#:tag "logging"]{Architecture and Garbage Collection} Immutable messages communicated on place-channels are first copied to a shared -garbage collector called the master. The master waits on a barrier until all places garbage -collectors have collected. Once the master is released it collects and resets -the barrier. +garbage collector called the master. Places are allowed to garbage collect +independently of one another. The master collector, however, has to pause all +mutators before it can collect garbage. @section[#:tag "compiling"]{Enabling Places in MzScheme Builds} diff --git a/src/mzscheme/src/places.c b/src/mzscheme/src/places.c index 7d3ff7c1a7..1b501158c9 100644 --- a/src/mzscheme/src/places.c +++ b/src/mzscheme/src/places.c @@ -18,7 +18,7 @@ static Scheme_Object *scheme_place_p(int argc, Scheme_Object *args[]); static Scheme_Object *scheme_places_deep_copy_in_master(Scheme_Object *so); static Scheme_Object *scheme_place_send(int argc, Scheme_Object *args[]); static Scheme_Object *scheme_place_recv(int argc, Scheme_Object *args[]); -static Scheme_Object *scheme_place_ch_p(int argc, Scheme_Object *args[]); +static Scheme_Object *scheme_place_channel_p(int argc, Scheme_Object *args[]); static Scheme_Object *def_place_exit_handler_proc(int argc, Scheme_Object *args[]); Scheme_Object *scheme_place_async_channel_create(); @@ -66,9 +66,9 @@ void scheme_init_place(Scheme_Env *env) PLACE_PRIM_W_ARITY("place-sleep", scheme_place_sleep, 1, 1, plenv); PLACE_PRIM_W_ARITY("place-wait", scheme_place_wait, 1, 1, plenv); PLACE_PRIM_W_ARITY("place?", scheme_place_p, 1, 1, plenv); - PLACE_PRIM_W_ARITY("place-ch-send", scheme_place_send, 1, 2, plenv); - PLACE_PRIM_W_ARITY("place-ch-recv", scheme_place_recv, 1, 1, plenv); - PLACE_PRIM_W_ARITY("place-ch?", scheme_place_ch_p, 1, 1, plenv); + PLACE_PRIM_W_ARITY("place-channel-send", scheme_place_send, 1, 2, plenv); + PLACE_PRIM_W_ARITY("place-channel-recv", scheme_place_recv, 1, 1, plenv); + PLACE_PRIM_W_ARITY("place-channel?", scheme_place_channel_p, 1, 1, plenv); #ifdef MZ_USE_PLACES REGISTER_SO(scheme_def_place_exit_proc); @@ -515,7 +515,7 @@ Scheme_Object *scheme_place_send(int argc, Scheme_Object *args[]) { scheme_place_async_send((Scheme_Place_Async_Channel *) args[0], mso); } else { - scheme_wrong_count_m("place-ch-send", 1, 2, argc, args, 0); + scheme_wrong_count_m("place-channel-send", 1, 2, argc, args, 0); } return scheme_true; } @@ -525,7 +525,7 @@ Scheme_Object *scheme_place_recv(int argc, Scheme_Object *args[]) { return scheme_place_async_recv((Scheme_Place_Async_Channel *) args[0]); } else { - scheme_wrong_count_m("place-ch-recv", 1, 2, argc, args, 0); + scheme_wrong_count_m("place-channel-recv", 1, 2, argc, args, 0); } return scheme_true; } @@ -624,7 +624,7 @@ Scheme_Object *scheme_place_async_channel_create() { return (Scheme_Object *)ch; } -static Scheme_Object *scheme_place_ch_p(int argc, Scheme_Object *args[]) +static Scheme_Object *scheme_place_channel_p(int argc, Scheme_Object *args[]) { return SAME_TYPE(SCHEME_TYPE(args[0]), scheme_place_async_channel_type) ? scheme_true : scheme_false; }