code review 39180043: go.blog: add "Inside the Go Playground" article

go.blog: add "Inside the Go Playground" article

[adg, 2013-12-12 06:08:29]

Hello r, rsc,

I'd like you to review this change to
https://code.google.com/p/go.blog

[adg, 2013-12-12 06:10:29]

You can view the post here: http://blog.go-build.appspot.com/playground

[r, 2013-12-12 06:43:58]

i addressed language only not correctness

it seems a bit incoherent, especially in the first half.  what are you trying to
say? make that clearer.

https://codereview.appspot.com/39180043/diff/220002/content/playground.article
File content/playground.article (right):

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:24: and integrated with the aforementioned services.
aforementioned is a pompous word.

"integrated with these services".

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:30: The playground service comprises three parts:
so is comprises.
s/comprises/has/

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:32: - A back end that runs on Google's servers. It
receives requests via RPC, compiles the user program using the gc tool chain,
executes the user program, and returns the program output (or compile errors) as
the RPC response.
s/requests via RPC/RPC requests/

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:51: If you want to play NaCl before then, you can
s/play/& with/

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:56: infrastructure from resource exhaustion, and so
programs are limited in the
s/, and//

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:59: This presents a problem, however, in that among
Go's key strengths are its
s/,/./ s/in that a/A/

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:60: concurrency, networking, and file system support.
file system support? i've never heard that mentioned as a strength. rewrite to
make file system access important but not a key strength.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:62: networking and the file system we obviously need
a network and a file system.
"demonstrate networking and file system" ... word missing?  better, rewrite.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:64: The playground as launched in 2010 had none of
those things.
this topic sentence is odd. it pulls us back in time but its position implies
forward motion. you need a bridging phrase.

Although all these things are supported today, the first version of the
playground, launched in 2010, had none of them.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:65: The current time was fixed at 10 November 2013,
`time.Sleep` had no effect,
s/2013/2009/

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:75: fake file system, making the playground more or
less equivalent to a normal Go
"more or less equivalent": ugly.

also the playground is not a tool chain, or equivalent to one. it's not even
close. it's a playground that handles single files under constrained execution.
what are you trying to say?

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:80: Programs built with the NaCl tool chain don't get
access to the local machine's
"don't get access" is colloquial. s/don't get/cannot/ s/to //

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:85: system kernel, user programs will use the fake
file system just as if it were
user programs see the file system exactly the same was as they would a real one.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:86: the real deal.
"real deal" colloq

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:88: The following example program writes some data to
a file, and then copies
s/some //  (what other amount could it be?)

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:94: `/dev` and an empty `/tmp` directory. The user
can manipulate the file system
the user can't, the program can.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:97: There is also a provision to load a Zip file into
the file system at init time
why is Zip capitalized?

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:143: The following program listens on a TCP port,
waits for an incoming connection,
s/T/For an executable example, run the following program. It listens.../

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:150: Network sockets are more complex than files
(although arguably they need not
drop the parenthetical by saying

The interface to the network is more complex than the one for files, so...

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:161: use, but they are also restricted in how much
wall time they can use.
s/wall/real/

walls don't have time.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:277: cached compile response. If found, it returns
the cached response, taking load
what is a 'compile response'? rephrase

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:278: off the back end for frequently executed
programs (such as those on the
"taking load off the back end" ugh.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:287: for setting up the user interface (the code and
output boxes, the run button, etc)
etc. has a period but s/etc/and so on/

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:298: function takes a bunch of HTML elements and
turns them into an interactive
"a bunch" colloq.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:300: playground on your own site. (See the conclusion
for more about this.)
don't put unique content in the conclusion!

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:306: is an implemenation of `Transport` that speaks
the HTTP-based protocol
implementation

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:311: To comply with
[[http://en.wikipedia.org/wiki/Same-origin_policy][same-origin policy]],
"the" missing

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:315: package does this proxying, and provides both a
standard and App Engine
both with?

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:345: and we are happy for your to use it on your own
site. All we ask is that
s/your/you/

[adg, 2013-12-12 08:16:31]

Have addressed all comments, still thinking about the structure of the first
half.

https://codereview.appspot.com/39180043/diff/220002/content/playground.article
File content/playground.article (right):

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:24: and integrated with the aforementioned services.
On 2013/12/12 06:43:58, r wrote:
> aforementioned is a pompous word.
> 
> "integrated with these services".

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:30: The playground service comprises three parts:
On 2013/12/12 06:43:58, r wrote:
> so is comprises.
> s/comprises/has/

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:32: - A back end that runs on Google's servers. It
receives requests via RPC, compiles the user program using the gc tool chain,
executes the user program, and returns the program output (or compile errors) as
the RPC response.
On 2013/12/12 06:43:58, r wrote:
> s/requests via RPC/RPC requests/

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:51: If you want to play NaCl before then, you can
On 2013/12/12 06:43:58, r wrote:
> s/play/& with/

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:56: infrastructure from resource exhaustion, and so
programs are limited in the
On 2013/12/12 06:43:58, r wrote:
> s/, and//

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:59: This presents a problem, however, in that among
Go's key strengths are its
On 2013/12/12 06:43:58, r wrote:
> s/,/./ s/in that a/A/

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:60: concurrency, networking, and file system support.
On 2013/12/12 06:43:58, r wrote:
> file system support? i've never heard that mentioned as a strength. rewrite to
> make file system access important but not a key strength.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:62: networking and the file system we obviously need
a network and a file system.
On 2013/12/12 06:43:58, r wrote:
> "demonstrate networking and file system" ... word missing?  better, rewrite.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:64: The playground as launched in 2010 had none of
those things.
On 2013/12/12 06:43:58, r wrote:
> this topic sentence is odd. it pulls us back in time but its position implies
> forward motion. you need a bridging phrase.
> 
> Although all these things are supported today, the first version of the
> playground, launched in 2010, had none of them.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:65: The current time was fixed at 10 November 2013,
`time.Sleep` had no effect,
On 2013/12/12 06:43:58, r wrote:
> s/2013/2009/

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:75: fake file system, making the playground more or
less equivalent to a normal Go
On 2013/12/12 06:43:58, r wrote:
> "more or less equivalent": ugly.
> 
> also the playground is not a tool chain, or equivalent to one. it's not even
> close. it's a playground that handles single files under constrained
execution.
> what are you trying to say?

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:80: Programs built with the NaCl tool chain don't get
access to the local machine's
On 2013/12/12 06:43:58, r wrote:
> "don't get access" is colloquial. s/don't get/cannot/ s/to //

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:85: system kernel, user programs will use the fake
file system just as if it were
On 2013/12/12 06:43:58, r wrote:
> user programs see the file system exactly the same was as they would a real
one.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:86: the real deal.
On 2013/12/12 06:43:58, r wrote:
> "real deal" colloq

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:88: The following example program writes some data to
a file, and then copies
On 2013/12/12 06:43:58, r wrote:
> s/some //  (what other amount could it be?)

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:94: `/dev` and an empty `/tmp` directory. The user
can manipulate the file system
On 2013/12/12 06:43:58, r wrote:
> the user can't, the program can.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:97: There is also a provision to load a Zip file into
the file system at init time
On 2013/12/12 06:43:58, r wrote:
> why is Zip capitalized?

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:143: The following program listens on a TCP port,
waits for an incoming connection,
On 2013/12/12 06:43:58, r wrote:
> s/T/For an executable example, run the following program. It listens.../

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:150: Network sockets are more complex than files
(although arguably they need not
On 2013/12/12 06:43:58, r wrote:
> drop the parenthetical by saying
> 
> The interface to the network is more complex than the one for files, so...

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:161: use, but they are also restricted in how much
wall time they can use.
On 2013/12/12 06:43:58, r wrote:
> s/wall/real/
> 
> walls don't have time.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:277: cached compile response. If found, it returns
the cached response, taking load
On 2013/12/12 06:43:58, r wrote:
> what is a 'compile response'? rephrase

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:278: off the back end for frequently executed
programs (such as those on the
On 2013/12/12 06:43:58, r wrote:
> "taking load off the back end" ugh.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:287: for setting up the user interface (the code and
output boxes, the run button, etc)
On 2013/12/12 06:43:58, r wrote:
> etc. has a period but s/etc/and so on/

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:298: function takes a bunch of HTML elements and
turns them into an interactive
On 2013/12/12 06:43:58, r wrote:
> "a bunch" colloq.

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:300: playground on your own site. (See the conclusion
for more about this.)
On 2013/12/12 06:43:58, r wrote:
> don't put unique content in the conclusion!

Done. Made it a section.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:306: is an implemenation of `Transport` that speaks
the HTTP-based protocol
On 2013/12/12 06:43:58, r wrote:
> implementation

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:311: To comply with
[[http://en.wikipedia.org/wiki/Same-origin_policy][same-origin policy]],
On 2013/12/12 06:43:58, r wrote:
> "the" missing

Done.

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:315: package does this proxying, and provides both a
standard and App Engine
On 2013/12/12 06:43:58, r wrote:
> both with?

Dropped the app engine mention

https://codereview.appspot.com/39180043/diff/220002/content/playground.articl...
content/playground.article:345: and we are happy for your to use it on your own
site. All we ask is that
On 2013/12/12 06:43:58, r wrote:
> s/your/you/

Done.

[r, 2013-12-12 15:04:21]

https://codereview.appspot.com/39180043/diff/260001/content/playground.article
File content/playground.article (right):

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:9: a web service that compiles and executes arbitrary
Go code returns the program
s/returns/and &/

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:12: If you're a Go programmer then you have probably
already used the playground,
s/,$//

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:24: and integrated with these services.
The implementation involves a variant operating system environment and runtime
and our description here assumes you have some familiarity with systems
programming using Go.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:32: - A back end that runs on Google's servers. It
receives RPC requests, compiles the user program using the gc tool chain,
executes the user program, and returns the program output (or compile errors) as
the RPC response.
s/compile errors/compilation errors/

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:45: (or "NaCl"), a technology originally developed by
Google to permit the safe
s/originally //

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:78: Go tool chain.
These facilities are described in the following sections.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:80: ** Faking the file system
you should put the time one first. it's really clever (don't bury the lead) and
also this puts it in the same order as in the section that introduces it

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:85: that is implemented by the `syscall` package
itself.
confusing change of reference. it's not nacl that does this, but go.

how about

Therefore, the implementation of Go on NaCl must simulate such accesses. It does
so by ...

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:93: .play -edit playground/os.go /^func main/,$
if you use WriteFile, why don't you use ReadFile? or if you use copy to read,
why don't you use copy to write?

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:166: This is because each running program consumes
resources on the compile server
first mention of a compile server

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:193: wait for a deadlock; the state when all
goroutines are blocked.
s/;/,/
s/when/where/

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:200: instant.
s/instant/*aneous/

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:205: the program output? It would be confusing to run
a program that sleeps and see
s/confusing/bizarre/

or better

It would be odd to see a program that sleeps run to completion correctly without
taking any time.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:209: five seconds. Try running it.
make it three. five makes the tombstones below too long

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:270: The playground front end is another simple
program (less than 100 lines).
fewer than 100 lines or
only about 100 lines or
shorter than 100 lines

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:279: When the front end receives a compile request it
first checks
s/compile/compilation/

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:281: cached RPC reponse. If found, it returns the
cached response.
response

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:281: cached RPC reponse. If found, it returns the
cached response.
maybe instead

to see if it has cached the results of a previous compilation of that source.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:283: (such as those on [[http://golang.org/][Go home
page]])
drop the parens

[adg, 2013-12-12 21:34:58]

Thank you so much for your detailed comments.

https://codereview.appspot.com/39180043/diff/260001/content/playground.article
File content/playground.article (right):

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:9: a web service that compiles and executes arbitrary
Go code returns the program
On 2013/12/12 15:04:22, r wrote:
> s/returns/and &/

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:12: If you're a Go programmer then you have probably
already used the playground,
On 2013/12/12 15:04:22, r wrote:
> s/,$//

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:24: and integrated with these services.
On 2013/12/12 15:04:22, r wrote:
> The implementation involves a variant operating system environment and runtime
> and our description here assumes you have some familiarity with systems
> programming using Go.

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:32: - A back end that runs on Google's servers. It
receives RPC requests, compiles the user program using the gc tool chain,
executes the user program, and returns the program output (or compile errors) as
the RPC response.
On 2013/12/12 15:04:22, r wrote:
> s/compile errors/compilation errors/

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:45: (or "NaCl"), a technology originally developed by
Google to permit the safe
On 2013/12/12 15:04:22, r wrote:
> s/originally //

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:78: Go tool chain.
On 2013/12/12 15:04:22, r wrote:
> These facilities are described in the following sections.

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:80: ** Faking the file system
On 2013/12/12 15:04:22, r wrote:
> you should put the time one first. it's really clever (don't bury the lead)
and
> also this puts it in the same order as in the section that introduces it

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:85: that is implemented by the `syscall` package
itself.
On 2013/12/12 15:04:22, r wrote:
> confusing change of reference. it's not nacl that does this, but go.
> 
> how about
> 
> Therefore, the implementation of Go on NaCl must simulate such accesses. It
does
> so by ...

actually, it's the Go/Nacl tool chain that does this. There's no reason a NaCl
program couldn't use the file system; our implementation just denies it.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:93: .play -edit playground/os.go /^func main/,$
On 2013/12/12 15:04:22, r wrote:
> if you use WriteFile, why don't you use ReadFile? or if you use copy to read,
> why don't you use copy to write?

To spice it up a bit. I used ReadFile instead.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:166: This is because each running program consumes
resources on the compile server
On 2013/12/12 15:04:22, r wrote:
> first mention of a compile server

and the last. used "back end" instead

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:193: wait for a deadlock; the state when all
goroutines are blocked.
On 2013/12/12 15:04:22, r wrote:
> s/;/,/
> s/when/where/

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:200: instant.
On 2013/12/12 15:04:22, r wrote:
> s/instant/*aneous/

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:205: the program output? It would be confusing to run
a program that sleeps and see
On 2013/12/12 15:04:22, r wrote:
> s/confusing/bizarre/
> 
> or better
> 
> It would be odd to see a program that sleeps run to completion correctly
without
> taking any time.

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:209: five seconds. Try running it.
On 2013/12/12 15:04:22, r wrote:
> make it three. five makes the tombstones below too long

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:270: The playground front end is another simple
program (less than 100 lines).
On 2013/12/12 15:04:22, r wrote:
> fewer than 100 lines or
> only about 100 lines or
> shorter than 100 lines

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:279: When the front end receives a compile request it
first checks
On 2013/12/12 15:04:22, r wrote:
> s/compile/compilation/

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:281: cached RPC reponse. If found, it returns the
cached response.
On 2013/12/12 15:04:22, r wrote:
> response

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:281: cached RPC reponse. If found, it returns the
cached response.
On 2013/12/12 15:04:22, r wrote:
> maybe instead
> 
> to see if it has cached the results of a previous compilation of that source.

Done.

https://codereview.appspot.com/39180043/diff/260001/content/playground.articl...
content/playground.article:283: (such as those on [[http://golang.org/][Go home
page]])
On 2013/12/12 15:04:22, r wrote:
> drop the parens

Done.

[adg, 2013-12-12 21:35:33]

+dsymonds

[rsc, 2013-12-12 22:06:59]

lgtm

[r, 2013-12-12 22:16:19]

LGTM

[dsymonds, 2013-12-12 22:22:40]

LGTM

[adg, 2013-12-12 22:27:17]

*** Submitted as
https://code.google.com/p/go/source/detail?r=a583c47e1fc3&repo=blog ***

go.blog: add "Inside the Go Playground" article

R=r, rsc, dsymonds
https://codereview.appspot.com/39180043