english
version "1.0"
identify "%Z%%M% %I% %E%"

#: Copyright (c) 2005 by Wayne C. Gramlich.
#, All rights reserved.

module long_jump

#: This module declares and implements an interface to the C longjmp
#, facility, a primative exception handling system.

define long_jump	#: {long_jump} type:
    external



#: {long_jump} procedure

procedure address_get@long_jump
    takes
	long_jump long_jump
    returns address
    external long_jump__address_get

    #: This procedure will return the address of {long_jump}.



procedure allocate@long_jump
    takes_nothing
    returns long_jump
    external long_jump__allocate

    #: This procedure will allocate and return a {long_jump} object.



procedure identical@long_jump
    takes
	long_jump1 long_jump
	long_jump2 long_jump
    returns logical

    #: This procedure will return {true} if {long_jump1} is equal
    #, to {long_jump2} and {false} otherwise.


procedure jump@long_jump
    takes
	long_jump long_jump
	value unsigned
    returns_nothing
    external long_jump__jump

    #: This procedure will perform a long jump operation on {long_jump}
    #, causing the last {set}@{long_jump} that used {long_jump} to
    #, return {value}.  {value} must be non-zero.  This procedure only
    #, returns if the jump fails.  Otherwise, it does not return,
    #, but instead transfers control to the saved context in {long_jump}.



procedure print@long_jump
    takes
	long_jump long_jump
	out_stream out_stream
    returns_nothing

    #: This procedure will print the contents of {long_jump} to {out_stream}.


procedure setup@long_jump
    routine_types
	procedure normal
	    takes_nothing
	    returns_nothing
	procedure failure
	    takes_nothing
	    returns_nothing
    takes
	long_jump long_jump
	normal normal
	failure failure
    returns logical
    external long_jump__setup

    #: This procedure will store procedure context information into
    #, {long_jump} and then invoke the {normal} procedure.  If some
    #, time during the execution of the {normal} procedure, a call
    #, to {jump}@({long_jump}) is performed, all execution of the
    #, code from {normal} down is brutally terminated with no chance
    #, to clean up and {failure} is invoked.  {true} is returned if
    #, {failure} is invoked and {false} if only {normal} is invoked.