From 5cff0299931d9f114ca3b3f40aa1e5bb62e2ad08 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Fri, 24 Feb 2012 13:08:11 +1100 Subject: [PATCH] doc/go1: document ProcessState Also reformat the "go fix" references to make them look better by using the non-CW space. Fixes #3087. R=golang-dev, bradfitz CC=golang-dev https://golang.org/cl/5695057 --- doc/go1.html | 60 ++++++++++++++++++++++++++++++++++------------------ doc/go1.tmpl | 60 ++++++++++++++++++++++++++++++++++------------------ 2 files changed, 78 insertions(+), 42 deletions(-) diff --git a/doc/go1.html b/doc/go1.html index 4bc4f66289..e9e33a69a0 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -242,7 +242,7 @@ There is no return value. Deleting a non-existent entry is a no-op.

Updating: -Running go fix will convert expressions of the form m[k] = ignored, +Running go fix will convert expressions of the form m[k] = ignored, false into delete(m, k) when it is clear that the ignored value can be safely discarded from the program and false refers to the predefined boolean constant. @@ -535,7 +535,7 @@ and template.

Updating: -Running go fix will update all imports and package renames for packages that +Running go fix will update all imports and package renames for packages that remain inside the standard repository. Programs that import packages that are no longer in the standard repository will need to be edited by hand. @@ -578,7 +578,7 @@ If they are installed, they now reside in $GOROOT/bin/tool. Updating: Code that uses packages in exp will need to be updated by hand, or else compiled from an installation that has exp available. -The go fix tool or the compiler will complain about such uses. +The go fix tool or the compiler will complain about such uses.

The package tree old

@@ -603,7 +603,7 @@ The packages in their new locations are: Updating: Code that uses packages now in old will need to be updated by hand, or else compiled from an installation that has old available. -The go fix tool will warn about such uses. +The go fix tool will warn about such uses.

Deleted packages

@@ -684,7 +684,7 @@ This table lists the old and new import paths:

Updating: -Running go fix will update imports of these packages to use the new import paths. +Running go fix will update imports of these packages to use the new import paths. Installations that depend on these packages will need to install them using a go install command.

@@ -749,7 +749,7 @@ to turn a string into an error. It replaces the old os.NewError.

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Code that defines error types with a String method will need to be updated by hand to rename the methods to Error.

@@ -768,7 +768,7 @@ that satisfies error and replaces the old os.Errno.

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Regardless, most code should use the os package rather than syscall and so will be unaffected.

@@ -836,7 +836,7 @@ its representation of file time stamps.

Updating: -The go fix tool will update many uses of the old time package to use the new +The go fix tool will update many uses of the old time package to use the new types and methods, although it does not replace values such as 1e9 representing nanoseconds per second. Also, because of type changes in some of the values that arise, @@ -851,7 +851,7 @@ may have the wrong type or require further analysis.

This section describes smaller changes, such as those to less commonly used packages or that affect -few programs beyond the need to run go fix. +few programs beyond the need to run go fix. This category includes packages that are new in Go 1.

@@ -879,7 +879,7 @@ If the argument size is too small or invalid, it is adjusted.

Updating: -Running go fix will update calls that assign the error to _. +Running go fix will update calls that assign the error to _. Calls that aren't fixed will be caught by the compiler and must be updated by hand.

@@ -899,7 +899,7 @@ to Writer and Reader. Package flate's

Updating -Running go fix will update old names and calls that assign the error to _. +Running go fix will update old names and calls that assign the error to _. Calls that aren't fixed will be caught by the compiler and must be updated by hand.

@@ -951,7 +951,7 @@ a function that returns a hash.Hash, such as md5.New.

Updating: -Running go fix will perform the needed changes. +Running go fix will perform the needed changes.

The crypto/x509 package

@@ -1021,7 +1021,7 @@ of the XML element being marshaled.

Updating: -Running go fix will update most uses of the package except for some calls to +Running go fix will update most uses of the package except for some calls to Unmarshal. Special care must be taken with field tags, since the fix tool will not update them and if not fixed by hand they will misbehave silently in some cases. For example, the old @@ -1185,7 +1185,7 @@ The previous behavior can be recreated by adding a nil argument to Existing implementations of hash.Hash will need to add a BlockSize method. Hashes that process the input one byte at a time can implement BlockSize to return 1. -Running go fix will update calls to the Sum methods of the various +Running go fix will update calls to the Sum methods of the various implementations of hash.Hash.

@@ -1233,7 +1233,7 @@ now panic if an attempt is made to register the same pattern twice.

Updating: -Running go fix will update the few programs that are affected except for +Running go fix will update the few programs that are affected except for uses of RawURL, which must be fixed by hand.

@@ -1349,7 +1349,7 @@ and

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.

The log/syslog package

@@ -1463,9 +1463,27 @@ Also, the function Wait is gone; only the method of the Process type persists.

+

+The Waitmsg type returned by +Process.Wait +has been replaced with a more portable +ProcessState +type with accessor methods to recover information about the +process. +Because of changes to Wait, the ProcessState +value always describes an exited process. +Portability concerns simplified the interface in other ways, but the values returned by the +ProcessState.Sys and +ProcessState.SysUsage +methods can be type-asserted to underlying system-specific data structures such as +syscall.WaitStatus and +syscall.Rusage on Unix. +

+

Updating: -All changes will be caught by the compiler and must be updated by hand. +Running go fix will drop a zero argument to Process.Wait. +All other changes will be caught by the compiler and must be updated by hand.

The os.FileInfo type

@@ -1550,7 +1568,7 @@ and

Updating: -Running go fix will update code that uses the old equivalent of the current os.FileInfo +Running go fix will update code that uses the old equivalent of the current os.FileInfo and os.FileMode API. Code that needs system-specific file details will need to be updated by hand. Code that uses the old POSIX error values from the os package @@ -1671,7 +1689,7 @@ have been renamed to runtime.NumCgoCall and runtime.NumGorout

Updating: -Running go fix will update code for the function renamings. +Running go fix will update code for the function renamings. Other code will need to be updated by hand.

@@ -1762,11 +1780,11 @@ for full details.

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.
§ Atoi persists but Atoui and Atof32 do not, so they may require -a cast that must be added by hand; the go fix tool will warn about it. +a cast that must be added by hand; the go fix tool will warn about it.

diff --git a/doc/go1.tmpl b/doc/go1.tmpl index 2f0b32607e..a08ef185f4 100644 --- a/doc/go1.tmpl +++ b/doc/go1.tmpl @@ -192,7 +192,7 @@ There is no return value. Deleting a non-existent entry is a no-op.

Updating: -Running go fix will convert expressions of the form m[k] = ignored, +Running go fix will convert expressions of the form m[k] = ignored, false into delete(m, k) when it is clear that the ignored value can be safely discarded from the program and false refers to the predefined boolean constant. @@ -459,7 +459,7 @@ and template.

Updating: -Running go fix will update all imports and package renames for packages that +Running go fix will update all imports and package renames for packages that remain inside the standard repository. Programs that import packages that are no longer in the standard repository will need to be edited by hand. @@ -502,7 +502,7 @@ If they are installed, they now reside in $GOROOT/bin/tool. Updating: Code that uses packages in exp will need to be updated by hand, or else compiled from an installation that has exp available. -The go fix tool or the compiler will complain about such uses. +The go fix tool or the compiler will complain about such uses.

The package tree old

@@ -527,7 +527,7 @@ The packages in their new locations are: Updating: Code that uses packages now in old will need to be updated by hand, or else compiled from an installation that has old available. -The go fix tool will warn about such uses. +The go fix tool will warn about such uses.

Deleted packages

@@ -608,7 +608,7 @@ This table lists the old and new import paths:

Updating: -Running go fix will update imports of these packages to use the new import paths. +Running go fix will update imports of these packages to use the new import paths. Installations that depend on these packages will need to install them using a go install command.

@@ -663,7 +663,7 @@ to turn a string into an error. It replaces the old os.NewError.

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Code that defines error types with a String method will need to be updated by hand to rename the methods to Error.

@@ -682,7 +682,7 @@ that satisfies error and replaces the old os.Errno.

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change. Regardless, most code should use the os package rather than syscall and so will be unaffected.

@@ -740,7 +740,7 @@ its representation of file time stamps.

Updating: -The go fix tool will update many uses of the old time package to use the new +The go fix tool will update many uses of the old time package to use the new types and methods, although it does not replace values such as 1e9 representing nanoseconds per second. Also, because of type changes in some of the values that arise, @@ -755,7 +755,7 @@ may have the wrong type or require further analysis.

This section describes smaller changes, such as those to less commonly used packages or that affect -few programs beyond the need to run go fix. +few programs beyond the need to run go fix. This category includes packages that are new in Go 1.

@@ -783,7 +783,7 @@ If the argument size is too small or invalid, it is adjusted.

Updating: -Running go fix will update calls that assign the error to _. +Running go fix will update calls that assign the error to _. Calls that aren't fixed will be caught by the compiler and must be updated by hand.

@@ -803,7 +803,7 @@ to Writer and Reader. Package flate's

Updating -Running go fix will update old names and calls that assign the error to _. +Running go fix will update old names and calls that assign the error to _. Calls that aren't fixed will be caught by the compiler and must be updated by hand.

@@ -855,7 +855,7 @@ a function that returns a hash.Hash, such as md5.New.

Updating: -Running go fix will perform the needed changes. +Running go fix will perform the needed changes.

The crypto/x509 package

@@ -925,7 +925,7 @@ of the XML element being marshaled.

Updating: -Running go fix will update most uses of the package except for some calls to +Running go fix will update most uses of the package except for some calls to Unmarshal. Special care must be taken with field tags, since the fix tool will not update them and if not fixed by hand they will misbehave silently in some cases. For example, the old @@ -1088,7 +1088,7 @@ The previous behavior can be recreated by adding a nil argument to Existing implementations of hash.Hash will need to add a BlockSize method. Hashes that process the input one byte at a time can implement BlockSize to return 1. -Running go fix will update calls to the Sum methods of the various +Running go fix will update calls to the Sum methods of the various implementations of hash.Hash.

@@ -1136,7 +1136,7 @@ now panic if an attempt is made to register the same pattern twice.

Updating: -Running go fix will update the few programs that are affected except for +Running go fix will update the few programs that are affected except for uses of RawURL, which must be fixed by hand.

@@ -1252,7 +1252,7 @@ and

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.

The log/syslog package

@@ -1366,9 +1366,27 @@ Also, the function Wait is gone; only the method of the Process type persists.

+

+The Waitmsg type returned by +Process.Wait +has been replaced with a more portable +ProcessState +type with accessor methods to recover information about the +process. +Because of changes to Wait, the ProcessState +value always describes an exited process. +Portability concerns simplified the interface in other ways, but the values returned by the +ProcessState.Sys and +ProcessState.SysUsage +methods can be type-asserted to underlying system-specific data structures such as +syscall.WaitStatus and +syscall.Rusage on Unix. +

+

Updating: -All changes will be caught by the compiler and must be updated by hand. +Running go fix will drop a zero argument to Process.Wait. +All other changes will be caught by the compiler and must be updated by hand.

The os.FileInfo type

@@ -1449,7 +1467,7 @@ and

Updating: -Running go fix will update code that uses the old equivalent of the current os.FileInfo +Running go fix will update code that uses the old equivalent of the current os.FileInfo and os.FileMode API. Code that needs system-specific file details will need to be updated by hand. Code that uses the old POSIX error values from the os package @@ -1556,7 +1574,7 @@ have been renamed to runtime.NumCgoCall and runtime.NumGorout

Updating: -Running go fix will update code for the function renamings. +Running go fix will update code for the function renamings. Other code will need to be updated by hand.

@@ -1647,11 +1665,11 @@ for full details.

Updating: -Running go fix will update almost all code affected by the change. +Running go fix will update almost all code affected by the change.
§ Atoi persists but Atoui and Atof32 do not, so they may require -a cast that must be added by hand; the go fix tool will warn about it. +a cast that must be added by hand; the go fix tool will warn about it.

-- 2.50.0