"

 COPYRIGHT (c) 1989 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

CompiledCode subclass:#Block

	instanceVariableNames:'home nargs sourcePos initialPC'

	classVariableNames:'InvalidNewSignal'

	poolDictionaries:''

	category:'Kernel-Methods'

!

!Block class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    Blocks are pieces of executable code which can be evaluated by sending

    them a value-message (''value'', ''value:'', ''value:value:'' etc).

    In smalltalk, Blocks provide the basic (and heavily used) mechanism

    for looping, enumerating collection elements, visitors, exception

    handling, unwinding, delayed execution and processes.

    Blocks are never created explicitely; the only creation

    is done by the compilers, when some sourceCode is compiled to either

    machine or byteCode.

    Blocks with arguments need a message of type ''value:arg1 ... value:argn''

    for evaluation; the number of arguments passed when evaluating must match

    the number of arguments the block was declared with otherwise an error is

    raised. Blocks without args need a ''value'' message for evaluation.

    Blocks keep a reference to the context where the block was declared -

    this allows blocks to access the methods arguments and/or variables.

    This is still true after the method has returned - since the

    block keeps this reference, the methods context will NOT die in this case.

    (i.e. Blocks are closures in Smalltalk/X)

    A return (via ^-statement) out of a block will force a return from the

    blocks method context (if it is still living) - this make the implementation

    of long-jumps and control structures possible.

    (If the method is not alive (i.e. has already returned), a return out of the 

     block will trigger an error)

    Long-jump is done by defining a catchBlock as ''[^ self]''

    somewhere up in the calling-tree. Then, to do the long-jump from out of some 

    deeply nested method, simply do: ''catchBlock value''.

    [Instance variables:]

      home        <Context>         the context where this block was created (i.e. defined)

      nargs       <SmallInteger>    the number of arguments the block expects

      sourcePos   <SmallInteger>    the character position of its source, in chars

      initialPC   <SmallInteger>    the start position within the byteCode

    [Class variables:]

      InvalidNewSignal              raised if a Block is tried to be created

    NOTICE: layout known by runtime system and compiler - do not change

    [author:]

    [see also:]

"

!

examples

"

    define a block and evaluate it:

    even here, blocks are involved: 

    (although, the compiler optimizes things if possible)

    here things become obvious:

    simple loops:

      not very objectOriented:

      using integer protocol:

      interval protocol:

    looping over collections:

      bad code:

      (only works with numeric-indexable collections)

      just as bad (well, marginally better ;-):

      (only works with numeric-indexable collections)

      the smalltalk way:

      (works with any collection)

    Rule: use enumeration protocol of the collection instead of

    processes:

      forking a lightweight process (thread):

      some with low prio:

    handling exceptions:

    performing cleanup actions:

    delayed execution (visitor pattern):

    (looking carefully into the example, 

     C/C++ programmers may raise their eyes ;-)

"

! !

!Block class methodsFor:'initialization'!

initialize

    "create signals raised by various errors"

    InvalidNewSignal isNil ifTrue:[

    ]

    "Modified: 22.4.1996 / 16:34:20 / cg"

! !

!Block class methodsFor:'instance creation'!

byteCode:bCode numArgs:numArgs sourcePosition:sourcePos initialPC:initialPC literals:literals

    "create a new cheap (homeless) block.

     Not for public use - this is a special hook for the compiler."

    |newBlock|

    newBlock := (super basicNew:(literals size)) 

    ^ newBlock

    "Modified: 24.6.1996 / 12:36:48 / stefan"

    "Created: 17.10.1996 / 14:04:17 / cg"

!

new

    "catch creation of blocks - only the system creates blocks"

    ^ InvalidNewSignal raise.

!

new:size

    "catch creation of blocks - only the system creates blocks"

    ^ InvalidNewSignal raise.

! !

!Block class methodsFor:'queries'!

isBuiltInClass

    "return true if this class is known by the run-time-system.

     Here, true is returned for myself, false for subclasses."

    ^ self == Block

    "Modified: 23.4.1996 / 15:55:58 / cg"

!

maxNumberOfArguments

    "return the maximum number of arguments a block can have.

     This is a limit in the VM, which may be removed in one of 

     the next versions ..."

%{  /* NOCONTEXT */

    RETURN (__MKSMALLINT(MAX_METHOD_ARGS));

%}

! !

!Block methodsFor:'Compatibility - ST/V'!

on:aSignal do:exceptionBlock

    "added for ST/V compatibility; evaluate the receiver,

     handling aSignal. The argument, exceptionBlock is evaluated

     if the signal is raised during evaluation.

     Warning: no warranty, if the code below mimics ST/V's behavior

     correctly - give me a note if it does not ."

    aSignal handle:[:ex |

	exceptionBlock value.

	ex return

    ] do:self

    "

     [

	1 foo

     ] on:MessageNotUnderstoodSignal do:[]

    "

! !

!Block methodsFor:'Compatibility - V''Age'!

argumentCount

    "VisualAge compatibility: alias for #numArgs.

     return the number of arguments I expect for evaluation"

    ^ nargs

    "Created: 15.11.1996 / 11:22:02 / cg"

!

valueOnReturnDo:aBlock

    "VisualAge compatibility: alias for #valueOnUnwindDo:

     evaluate the receiver - when some method sent within unwinds 

     (i.e. does a long return), evaluate the argument, aBlock.

     This is used to make certain that cleanup actions 

     (for example closing files etc.) are executed regardless of error actions.

     Q: is this the exact semantics of V'Ages method ?

    ^ self valueOnUnwindDo:aBlock

    "Created: 15.11.1996 / 11:38:37 / cg"

! !

!Block methodsFor:'accessing'!

home

    "return the receivers home context (the context where it was

     created). For cheap blocks, nil is returned"

    ^ home

!

method

    "return the receivers method 

     (the method where the block was created)."

    home notNil ifTrue:[

	^ home method

    ].

    ^ nil

!

methodHome

    "return the receivers method home context (the context where it was

     defined). For cheap blocks, nil is returned"

    home notNil ifTrue:[

	^ home methodHome

    ].

    ^ home

!

numArgs

    "return the number of arguments I expect for evaluation"

    ^ nargs

! !

!Block methodsFor:'conversion'!

varArgs

    "convert myself into a varArg block;

     this one has 1 formal argument, which gets the list

     of actual arguments when evaluated."

    nargs ~~ 1 ifTrue:[

    ].

    self changeClassTo:VarArgBlock.

    ^ self

    "

     |b|

     b := [:argList | argList printCR] varArgs.

     b value.

     b value:'arg1' value:'arg2' value:'arg3' value:'arg4'

    "

    "Modified: 23.1.1997 / 04:54:41 / cg"

! !

!Block methodsFor:'copying'!

deepCopy

    "raise an error - deepCopy is not allowed for blocks"

    ^ self deepCopyError

! !

!Block methodsFor:'error handling'!