[squeak-dev] Comment improvements

Eliot Miranda eliot.miranda at gmail.com
Wed Nov 25 18:27:29 UTC 2015



> On Nov 25, 2015, at 9:40 AM, Bert Freudenberg <bert at freudenbergs.de> wrote:
> 
> … from vm-dev list. Who’d like to take care of this? :)

I will.  I just wanted the message thread to be read here.

> 
> - Bert -
> 
>> Begin forwarded message:
>> 
>> From: Eliot Miranda <eliot.miranda at gmail.com>
>> Subject: [Vm-dev] Re: [Pharo-dev] what is exactly flushCache?
>> Date: 25. November 2015 18:25:01 MEZ
>> To: Pharo Development List <pharo-dev at lists.pharo.org>
>> Cc: vm-dev at lists.squeakfoundation.org
>> Reply-To: Squeak Virtual Machine Development Discussion <vm-dev at lists.squeakfoundation.org>
>> 
>> Hi Stef,
>> 
>>> On Nov 24, 2015, at 12:00 PM, stepharo <stepharo at free.fr> 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."
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20151125/1b9e4622/attachment.htm


More information about the Squeak-dev mailing list