From 8afc6008a8319f4b13b2fa4d50062092f274084f Mon Sep 17 00:00:00 2001
From: Russ Cox <rsc@golang.org>
Date: Mon, 13 Jul 2009 15:54:41 -0700
Subject: [PATCH] add note about once and closures

R=r
DELTA=13  (13 added, 0 deleted, 0 changed)
OCL=31535
CL=31549
---
 src/pkg/once/once.go | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/pkg/once/once.go b/src/pkg/once/once.go
index 6047df2364..a87189ccc8 100644
--- a/src/pkg/once/once.go
+++ b/src/pkg/once/once.go
@@ -23,6 +23,19 @@ var joblock sync.Mutex;
 // If multiple processes call Do(f) simultaneously
 // with the same f argument, only one will call f, and the
 // others will block until f finishes running.
+//
+// Since a func() expression typically evaluates to a differerent
+// function value each time it is evaluated, it is incorrect to
+// pass such values to Do.  For example,
+// 	func f(x int) {
+//		Do(func() { fmt.Println(x) })
+//	}
+// behaves the same as
+//	func f(x int) {
+//		fmt.Println(x)
+//	}
+// because the func() expression in the first creates a new
+// func each time f runs, and each of those funcs is run once.
 func Do(f func()) {
 	joblock.Lock();
 	j, present := jobs[f];