Special Operator return-from

Syntax:

7.7.0 7

Arguments and Values:

name—a block tag; not evaluated.

result—a form; evaluated. The default is nil.

Description:

Returns control and multiple values₂ from a lexically enclosing block.

A block form named name must lexically enclose the occurrence of return-from; any values yielded by the evaluation of result are immediately returned from the innermost such lexically enclosing block.

This is all said in a concept section now. --sjl 7 Mar 92 \issue{EXIT-EXTENT:MINIMAL} When a transfer of control is initiated by \specref{return-from}, the following events occur before the transfer of control is complete. Note that for \specref{return-from}, the \term{exit point} is the corresponding \specref{block} \term{form}. \beginlist \itemitem{1.} Intervening \term{exit points} are ``abandoned'' (\ie their \term{extent} ends and it is no longer valid to attempt to transfer control through them). \itemitem{2.} The cleanup clauses of any intervening \specref{unwind-protect} clauses are evaluated. \itemitem{3.} Intervening dynamic \term{bindings} of \declref{special} variables and \term{catch tags} are undone. what about condition handlers and restarts? --sjl 5 Mar 92 \itemitem{4.} The \term{extent} of the \term{exit point} being invoked ends, and control is passed to the target. \endlist The extent of an exit being ``abandoned'' because it is being passed over ends as soon as the transfer of control is initiated. That is, event 1 occurs at the beginning of the initiation of the transfer of control. The consequences are undefined if an attempt is made to transfer control to an \term{exit point} whose \term{dynamic extent} has ended. Moon had me add the part about "interleaved" -kmp 13-Feb-92 Events 2 and 3 are actually performed interleaved, in the order corresponding to the reverse order in which they were established. The effect of this is that the cleanup clauses of an \specref{unwind-protect} sees the same dynamic \term{bindings} of variables and \term{catch tags} as were visible when the \specref{unwind-protect} was entered. Event 4 occurs at the end of the transfer of control. Dussud removed some additional detailed discussion here about longer extents, how events are interwoven, etc. \endissue{EXIT-EXTENT:MINIMAL}

The transfer of control initiated by return-from is performed as described in Section 5.2 (Transfer of Control to an Exit Point).

Examples:

 (block alpha (return-from alpha) 1) → NIL
 (block alpha (return-from alpha 1) 2) → 1
 (block alpha (return-from alpha (values 1 2)) 3) → 1, 2
 (let ((a 0))
    (dotimes (i 10) (incf a) (when (oddp i) (return)))
    a) → 2
 (defun temp (x)
    (if x (return-from temp 'dummy))
    44) → TEMP
 (temp nil) → 44
 (temp t) → DUMMY
 (block out
   (flet ((exit (n) (return-from out n)))
     (block out (exit 1)))
   2) → 1
 (block nil   
   (unwind-protect (return-from nil 1)
     (return-from nil 2)))
→ 2
 (dolist (flag '(nil t))
   (block nil
     (let ((x 5))
       (declare (special x))
       (unwind-protect (return-from nil)
         (print x))))
   (print 'here))
⊳ 5
⊳ HERE
⊳ 5
⊳ HERE
→ NIL
 (dolist (flag '(nil t))
   (block nil
     (let ((x 5))
       (declare (special x))
       (unwind-protect
           (if flag (return-from nil))
         (print x))))
   (print 'here))
⊳ 5
⊳ HERE
⊳ 5
⊳ HERE
→ NIL

The following has undefined consequences because the block form exits normally before the return-from form is attempted.

 (funcall (block nil #'(lambda () (return-from nil)))) is an error.

Affected By:

None.

Exceptional Situations:

None.

See Also:

block, return, Section 3.1 (Evaluation)

Notes:

None.