"

 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:#Method

	instanceVariableNames:'source sourcePosition category package'

	classVariableNames:'PrivateMethodSignal LastFileReference LastSourceFileName

		LastWhoClass'

	poolDictionaries:''

	category:'Kernel-Methods'

!

!Method 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

"

    this class defines protocol for executable methods;

    both compiled and interpreted methods are represented by this class.

    Compiled methods have a non-nil code field, while interpreted methods have

    a nil code field and non-nil byteCode field.

    If there are both non-nil code and bytecode fields, the VM will execute

    the machine-code of a method. If both are nil when executed, a noByteCode

    message is sent by the VM to the method where a signal is raised.

    The methods sourcecode is represented by source and sourcePosition:

    - if sourcePosition is a Number, the source-field is the fileName and

      sourcePosition is the character offset of the source-chunk in this source file.

    - If sourcePosition is nil, the source is the string in the source field.

    (an old version used ExternalString instances here, but that lead to

     10000 additional little objects ...)

    The flags field defines things like the number of method-locals,

    method arguments and stack requirements (for interpreted methods).

    Do not depend on any value in the flags field - it may change without

    notice.

    Notice, that in ST/X, method can be subclassed; executable code is

    identified not by being a subclass of Block or Method, but instead by

    having the executable flag bit set in the class. The VM can execute anything

    which is identified as executable (assuming that the first instance variable

    is the machine-code address) - this allows for easy future extension.

    [Instance variables:]

        source          <String>        the source itself (if sourcePosition isNil)

                                        or the fileName where the source is found

        sourcePosition  <Integer>       the position of the methods chunk in the file

        category        <Symbol>        the methods category

        package         <Symbol>        the package, in which the methods was defined

    [Class variables:]

        PrivateMethodSignal             raised on privacy violation (see docu)

        LastFileReference               weak reference to the last sourceFile

        LastSourceFileName              to speedup source access via NFS

    WARNING: layout known by compiler and runtime system - dont change

    [author:]

        Claus Gittinger

"

!

dynamicMethods

"

    On systems which support dynamic loading of machine code (SYS5.4, Linux),

    methods may now be compiled to machine code from within the browser,

    and the resulting machine code object be loaded in.

    The ObjectFileLoader keeps (weak) handles to the resulting methods and

    invalidates the corresponding method objects, if the underlying methods

    object code is unloaded.

    Invalid methods will trap into the debugger when executed;

    also, the browser marks them as '(* not executable *)' in its method list.

"

!

privacy 

"

    ST/X includes an EXPERIMENTAL implementation of method privacy.

    Individual methods may be set to private or protected via the

    #setPrivate and #setProtected messages. Also, categories may be

    filedIn as a whole as private using #privateMethodsFor: or as

    protected using #protectedMethodsFor: instead of the well known #methodsFor:.

    The additional #publicMethodsFor: is for documentation purposes, and

    is equivalent to #methodsFor: (also to support fileIn of ENVY methods).

    Private methods may be executed only when called via a self or super-send

    from the superclass, the class itself or subclasses.

    Protected methods may not be called from subclasses, i.e. they may only

    be called via self sends from within the current class.

    (i.e. private methods are less private than protected ones)

    When such a situation arises, the VM (runtime system) will raise the

    PrivateMethodSignal exception (if nonNil), which usually brings you into the

    debugger.

    If PrivateMethodSignal is nil, the VM will not check for this, and

    execution is as usual. (you may want to nil-it for production code,

    and leave it non nil during development).

    NOTICE: there is no (not yet ?) standard defined for method privacy,

    however, the interface was designed to be somewhat ENVY compatible (from

    what can be deduced by reading PD code).

    Also, the usability of privacy is still to be tested.

    This interface, the implementation and the rules for when a privacy violation

    may change (in case of some ANSI standard being defined).

    Be warned and send me suggestions & critics (constructive ;-)

"

! !

!Method class methodsFor:'initialization'!

initialize

    "create signals"

    PrivateMethodSignal isNil ifTrue:[

        "EXPERIMENTAL"

        PrivateMethodSignal := ExecutionErrorSignal newSignalMayProceed:true.

        PrivateMethodSignal nameClass:self message:#privateMethodSignal.

        PrivateMethodSignal notifierString:'attempt to execute private/protected method'.

    ]

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

! !

!Method class methodsFor:'Signal constants'!

privateMethodSignal

    "return the signal raised when a private/protected method is called

     by some other object (i.e. not a self- or super send)"

    ^ PrivateMethodSignal

! !

!Method class methodsFor:'binary storage'!

binaryDefinitionFrom: stream manager: manager

    "read my definition from stream."

    |cls sel|

    "type-byte"

    stream nextByte == 0 ifTrue:[

	"

	 built-in method

	"

	cls := manager nextObject.

	sel := manager nextObject.

	"

	 mhmh - on the source system, this was a machinecode

	 method, while here its an interpreted one ...

	"

	cls isLoaded ifFalse:[

	    cls autoload

	].

	^ cls compiledMethodAt:sel

    ].

    "

     bytecode method

    "

    ^ super binaryDefinitionFrom:stream manager:manager

!

binaryFullDefinitionFrom:stream manager:manager

    "retrieve a full bytecoded-method."

    |snapId cat flags code lits m sourceFilename sourcePos source|

    snapId := manager nextObject.

    cat := manager nextObject.

    flags := manager nextObject.

    lits := manager nextObject.

    sourceFilename := manager nextObject.

    sourcePos := manager nextObject.

    sourcePos isNil ifTrue:[

	source := manager nextObject.

    ].

    code := manager nextObject.

    snapId == ObjectMemory snapshotID ifTrue:[

	ObjectMemory incrementSnapshotID

    ].

    m := Method basicNew.

    cat notNil ifTrue:[m category:cat].

    m flags:flags.

    m literals:lits.

    m byteCode:code.

    sourcePos isNil ifTrue:[

	m source:source

    ] ifFalse:[

	m sourceFilename:sourceFilename position:sourcePos

    ].

    ^ m

    "Created: 16.1.1996 / 14:44:08 / cg"

! !

!Method 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 == Method

    "Modified: 23.4.1996 / 15:59:50 / cg"

!

maxNumberOfArguments

    "this limit will be removed in one of the next versions ..."

    ^ 15  "cannot be easily changed; should ask the VM about this number"

!

methodPrivacySupported

    "return true, if the system was compiled to support methodPrivacy.

     You should not depend on that feature being available."

%{  /* NOCONTEXT */

#if defined(F_PRIVATE) || defined(F_CLASSPRIVATE)

    RETURN (true);

#else

    RETURN (false);

#endif

%}

! !

!Method class methodsFor:'special'!

flushSourceStreamCache

    LastSourceFileName := nil

    "Created: 9.2.1996 / 19:05:28 / cg"

! !

!Method methodsFor:'accessing'!

category

    "return the methods category or nil"

    ^ category

!

category:aStringOrSymbol

    "set the methods category"

    category := aStringOrSymbol asSymbol

!

clearCalledFlag

    "mark the method as never called.

     The called flag will be set by the interpreter whenever a method

     is called for the very first time, to support coverage tests.

     This is EXPERIMENTAL, nonStandard and not yet fully implemented."

%{  /* NOCONTEXT */

#ifdef F_CALLED

    int f = __intVal(__INST(flags));

    f &= ~F_CALLED;

    __INST(flags) = __MKSMALLINT(f);

#endif

%}

!

comment

    "return the methods comment.

     This is done by searching for and returning the first comment

     from the methods source (excluding any double-quotes). 

     Returns nil if there is no comment (or source is not available)."

    |src comments parser|

    src := self source.

    src isNil ifTrue:[^ nil].

    parser := Parser for:src in:nil.

    parser ignoreErrors; ignoreWarnings; saveComments:true.

    parser parseMethodSpec.

    comments := parser comments.

    comments size == 0 ifTrue:[^ nil].

    (comments first endsWith:'}') ifTrue:[

        ^ comments at:2 ifAbsent:nil

    ].

    ^ comments first.

    "

     (Method compiledMethodAt:#comment) comment  

     (Object class compiledMethodAt:#infoPrinting:) comment  

    "

    "Modified: 22.4.1996 / 19:53:58 / cg"

!

flags

    "return the flags (number of method variables, stacksize etc.).

     Dont depend on the values in the flag field - its interpretations

     may change without notice."

    ^ flags

    "Modified: 8.3.1996 / 13:20:48 / cg"

!

getSource

    ^ source

!

numberOfMethodArgs

    "return the number of arguments, the method expects." 

%{  /* NOCONTEXT */

    /* made this a primitive to get define in stc.h */

#ifdef F_NARGS

    RETURN (__MKSMALLINT((__intVal(__INST(flags)) & F_NARGS) >> F_NARGSHIFT));

#endif

%}

.

    "

     The old implementation simply counted the arguments from

     the methods source - new versions include this information

     in the flag instVar, for more security in #perform:

    "

    ^ self methodArgNames size

!

numberOfMethodVars

    "return the number of method local variables. 

     Do not depend on the returned value - future optimizations

     may change things here (i.e. when moving block-locals into

     surrounding method for inlining).

     - for debugging only."

%{  /* NOCONTEXT */

    /* made this a primitive to get define in stc.h */

    RETURN (__MKSMALLINT((__intVal(__INST(flags)) & F_NVARS) >> F_NVARSHIFT));

%}

!

package

    "return the package-symbol"

    ^ package

!

package:aSymbol

    "set the package-symbol"

    package := aSymbol

!

source

    "return the sourcestring for the receiver"

    |aStream fileName junk w myClass mgr className|

    "

     if sourcePosition is nonNil, its the fileName and

     sourcePosition is the offset.

     Otherwise, source is the real source

    "

    sourcePosition isNil ifTrue:[^ source].

    source notNil ifTrue:[

"/

"/ original (old) code:

"/

"/        aStream := Smalltalk systemFileStreamFor:('source/' , source).

"/        aStream notNil ifTrue:[

"/            aStream position:sourcePosition.

"/            junk := aStream nextChunk.

"/            aStream close

"/        ]

        "/ keep the last source file open, because open/close

        "/ operations maybe slow on NFS-mounted file systems.

        "/ Since the reference to the file is weak, it will be closed

        "/ automatically if the file is not referenced for a while. 

        "/ Neat trick.

        LastSourceFileName = source ifTrue:[

            aStream := LastFileReference at:1.

        ].

        aStream isNil ifTrue:[

            "/

            "/ if there is no SourceManager, look in standard places

            "/ first

            "/

            (mgr := Smalltalk at:#SourceCodeManager) isNil ifTrue:[

                fileName := Smalltalk getSourceFileName:source.

                fileName notNil ifTrue:[

                    aStream := fileName asFilename readStream.

                ].

            ].

            aStream isNil ifTrue:[

                "/

                "/ nope - ask my class for the source (this also invokes the SCMgr)

                "/

                w := self who.

                w notNil ifTrue:[

                    myClass := w at:1.

                    aStream := myClass sourceStreamFor:source.

                ].

                aStream isNil ifTrue:[

                    "/

                    "/ nope - look in standard places 

                    "/ (if there is a source-code manager - otherwise, we already did that)

                    "/

                    mgr notNil ifTrue:[

                        fileName := Smalltalk getSourceFileName:source.

                        fileName notNil ifTrue:[

                            aStream := fileName asFilename readStream.

                        ]

                    ].

                    "/

                    "/ final chance: try current directory

                    "/

                    aStream isNil ifTrue:[

                        aStream := source asFilename readStream.

                    ]

                ].

                (aStream isNil and:[w isNil and:[source notNil]]) ifTrue:[

                    "/

                    "/ mhmh - seems to be a method which used to be in some

                    "/ class, but has been overwritten by another or removed.

                    "/ (i.e. it has no containing class anyMore)

                    "/ try to guess the class from the sourceFileName.

                    "/ and retry.

                    "/

                    className := Smalltalk classNameForFile:source.

                    className knownAsSymbol ifTrue:[

                        myClass := Smalltalk at:className asSymbol ifAbsent:nil.

                        myClass notNil ifTrue:[

                            aStream := myClass sourceStreamFor:source.

                        ]

                    ]

                ]                

            ]

        ].

        aStream notNil ifTrue:[

            aStream position:sourcePosition.

            junk := aStream nextChunk.

            "

             keep a weak reference - it may be needed again soon ...

            "

            LastFileReference isNil ifTrue:[

                LastFileReference := WeakArray new:1

            ].

            LastFileReference at:1 put:aStream.

            LastSourceFileName := source

        ]