net/http: explain more how Pusher.Push works

This will clarify that the resources are not completely pushed yet when `Push` returns and that it starts a separate goroutine. This might be implementation dependant but as I believe there is currently only one implementation it should be added to the documentation of the interface which most people will look up first.

Change-Id: Id151c5563fd0c4e611eb1d93b4f64bf747ddf6d4
GitHub-Last-Rev: 1f46eb9a081f4529abc04026589ffd463be579b3
GitHub-Pull-Request: golang/go#25025
Reviewed-on: https://go-review.googlesource.com/c/108939
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/net/http/http.go b/src/net/http/http.go
index ce0eceb1de303b67602f32235f756f011d21cc2a..30d1a52b63190a3b402ea5a3bccde4062166dd5c 100644 (file)
--- a/src/net/http/http.go
+++ b/src/net/http/http.go
@@ -135,6 +135,10 @@ type Pusher interface {
        // data that may trigger a request for URL X. This avoids a race where the
        // client issues requests for X before receiving the PUSH_PROMISE for X.
        //
+       // Push will run in a separate goroutine making the order of arrival
+       // non-deterministic. Any required synchronization needs to be implemented
+       // by the caller.
+       //
        // Push returns ErrNotSupported if the client has disabled push or if push
        // is not supported on the underlying connection.
        Push(target string, opts *PushOptions) error