From 5bb29fb1160ed9c727a2b83aa9cf7c082ac5de26 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 25 Mar 2010 17:59:59 -0700 Subject: [PATCH] spec changes for panic and recover. R=rsc, gri CC=golang-dev https://golang.org/cl/763041 --- doc/go_spec.html | 186 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 178 insertions(+), 8 deletions(-) diff --git a/doc/go_spec.html b/doc/go_spec.html index 828afd8dc5..46dc33e8a0 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1108,7 +1108,7 @@ The comparison operators == and != key type; thus the key type must be a boolean, numeric, string, pointer, function, interface, map, or channel type. If the key type is an interface type, these comparison operators must be defined for the dynamic key values; -failure will cause a run-time error. +failure will cause a run-time panic.

@@ -2397,7 +2397,8 @@ or for a of type S where S is a run-time panic occurs

@@ -2409,7 +2410,8 @@ where T is a string type:

  • a[x] is the byte at index x and the type of a[x] is byte
  • a[x] may not be assigned to -
  • if the index x is out of range, a run-time exception occurs
    • +
  • if the index x is out of range, + a run-time panic occurs

    • @@ -2542,8 +2544,9 @@ of x implements the interface T (§run-time panic occurs. +In other words, even though the dynamic type of x is known only at run-time, the type of x.(T) is known to be T in a correct program.

    @@ -2562,7 +2565,7 @@ the result of the assertion is a pair of values with types (T, bool)(x.(T), true); otherwise, the expression returns (Z, false) where Z is the zero value for type T. -No run-time exception occurs in this case. +No run-time panic occurs in this case. The type assertion in this construct thus acts like a function call returning a value and a boolean indicating success. (§Assignments)

    @@ -4281,7 +4284,7 @@ Deferred function calls are executed in LIFO order immediately before the surrounding function returns, after the return values, if any, have been evaluated, but before they are returned to the caller. For instance, if the deferred function is -a function literal and the surrounding +a function literal and the surrounding function has named result parameters that are in scope within the literal, the deferred function may access and modify the result parameters before they are returned. @@ -4510,6 +4513,150 @@ var im = imag(b) // has type float var rl = real(c64) // type float32 +

    Handling panics

    + +

    Two built-in functions, panic and recover, +assist in reporting and handling run-time panics +and program-defined error conditions. +

    + +
    +func panic(interface{})
+func recover() interface{}
+
    + +

    +TODO: Most of this text could move to the respective +comments in runtime.go once the functions are implemented. +They are here, at least for now, for reference and discussion. + +

    + +

    +When a function F calls panic, normal +execution of F stops immediately. Any functions whose +execution was deferred by the +invocation of F are run in the usual way, and then +F returns to its caller. To the caller, F +then behaves like a call to panic, terminating its own +execution and running deferred functions. This continues until all +functions in the goroutine have ceased execution, in reverse order. +At that point, the program is +terminated and the error condition is reported, including the value of +the argument to panic. This termination sequence is +called panicking. +

    + +

    +The recover function allows a program to manage behavior +of a panicking goroutine. Executing a recover call +inside a deferred function (but not any function called by it) stops +the panicking sequence by restoring normal execution, and retrieves +the error value passed to the call of panic. If +recover is called outside the deferred function it will +not stop a panicking sequence. In this case, and when the goroutine +is not panicking, recover returns nil. +

    + +

    +If the function defined here, +

    + +
    +func f(hideErrors bool) {
+	defer func() {
+		if x := recover(); x != nil {
+			println("panicking with value", v)
+			if !hideErrors {
+				panic(x)  // go back to panicking
+			}
+		}
+		println("function returns normally") // executes only when hideErrors==true
+	}()
+	println("before")
+	p()
+	println("after")	// never executes
+}
+
+func p() {
+	panic(3)
+}
+
    + +

    +is called with hideErrors=true, it prints +

    + +
    +before
+panicking with value 3
+function returns normally
+
    + +

    +and resumes normal execution in the function that called f. Otherwise, it prints +

    + +
    +before
+panicking with value 3
+
    + +

    +and, absent further recover calls, terminates the program. +

    + +

    +Since deferred functions run before assigning the return values to the caller +of the deferring function, a deferred invocation of a function literal may modify the +invoking function's return values in the event of a panic. This permits a function to protect its +caller from panics that occur in functions it calls. +

    + +
    +func IsPrintable(s string) (ok bool) {
+	ok = true
+	defer func() {
+		if recover() != nil {
+			println("input is not printable")
+			ok = false
+		}
+		// Panicking has stopped; execution will resume normally in caller.
+		// The return value will be true normally, false if a panic occurred.
+	}
+	panicIfNotPrintable(s)	// will panic if validations fails.
+}
+
    + +

    Bootstrapping

    @@ -4524,7 +4671,6 @@ Function Behavior print prints all arguments; formatting of arguments is implementation-specific println like print but prints spaces between arguments and a newline at the end -panic like print, aborts execution after printing @@ -4822,6 +4968,28 @@ Implementation restriction: The compiler assumes package main is not imported by any other package.

    +

    Run-time panics

    + +

    +Execution errors such as attempting to index an array out +of bounds trigger a run-time panic equivalent to a call of +the built-in function panic +with a value of the implementation-defined interface type runtime.Error. +That type defines at least the method +String() string. The exact error values that +represent distinct run-time error conditions are unspecified, +at least for now. +

    + +
    +package runtime
+
+type Error interface {
+	String() string
+	// and perhaps others
+}
+
    +

    System considerations

    Package unsafe

    @@ -4942,4 +5110,6 @@ The following minimal alignment properties are guaranteed:
  • Gccgo allows only one init() function per source file.
  • Deferred functions cannot access the surrounding function's result parameters.
  • Function results are not addressable.
    • +
  • Recover is not implemented.
    • +
  • The implemented version of panic differs from its specification.