Comment improvements

- Bert -

Begin forwarded message:

From: Eliot Miranda <[hidden email]>

Subject: [Vm-dev] Re: [Pharo-dev] what is exactly flushCache?

Date: 25. November 2015 18:25:01 MEZ

To: Pharo Development List <[hidden email]>

Cc: [hidden email]

Reply-To: Squeak Virtual Machine Development Discussion <[hidden email]>

Hi Stef,

On Nov 24, 2015, at 12:00 PM, stepharo <[hidden email]> wrote:

Thanks for this great explanation and yes I know about this cache but I do not why
I was wondering that we did not need to update it from the image.
Now I would like to add such comment inside the system because I like self explanation.

"See Object documentation whatIsAPrimitive." gets frustrates me.

It's still appropriate to explain to newbies what primitives are and how they are invoked.  Interesting to consider what the minimum knowledge programmers have when first using the system.  Do they know, for example, that methods contain bytecode for a stack machine, or that underneath the system is a virtual machine containing a bytecode execution engine, a set of primitives and (a) garbage collector(s)?

So I imagine that is Behavior flushCache flushing for the class in the class,selector pair.

Again because of inheritance the VM can't just flush entries for a specific class, so the VM responds to Behavior>>flushCache flushes the entire cache.

What would be a good place to add such comment? MethodDictionary. It sounds reasonable to me but tell me.

If the comments in the various flushCache implementations are correct and reference each other then I think that's enough.

TBehavior >> flushCache
    "Tell the interpreter to remove the contents of its method lookup cache, if it has
    one.  Essential.  See Object documentation whatIsAPrimitive."

    <primitive: 89>
    self primitiveFailed

I would rewrite this to say

"Tell the virtual machine to remove the contents of its method lookup caches, if it has any.  This must be done when the system modifies the class hierarchy so that message lookups reflect the revised organization.  c.f. Symbol>>flushCache & CompiledMethod>>flushCache.  Essential.  See Object documentation whatIsAPrimitive."

Symbol >> flushCache
    "Tell the interpreter to remove all entries with this symbol as a selector from its method lookup cache, if it has one.  This primitive must be called whenever a method is redefined or removed.
    NOTE:  Only one of the two selective flush methods (Symbol or CompiledMethod) needs to be used."

    <primitive: 119>

I would rewrite this to say

"Tell the virtual machine to remove all entries with this symbol as a selector from its method lookup caches, if it has any.  This must be done whenever a method is added, redefined or removed, so that message lookups reflect the revised organization.  c.f. Behavior>>flushCache & CompiledMethod>>flushCache.  Essential.  See Object documentation whatIsAPrimitive."

CompiledMethod >> flushCache
    "Tell the interpreter to remove all references to this method from its method lookup cache, if it has one. This primitive must be called whenever a method is redefined or removed.
    NOTE:  Only one of two selective flush methods (Symbol or CompiledMethod) needs to be used."

    <primitive: 116>

I would rewrite this to say

"Tell the virtual machine to remove all references to this method from its method lookup caches, and to discard any optimized version of the method, if it has any of these.  This must be done whenever a method is modified in place, such as modifying its literals or machine code, to reflect the revised code.  c.f. Behavior>>flushCache & Symbol>>flushCache.  Essential.  See Object documentation whatIsAPrimitive."