incubator-kato-spec mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stuart Monteith <stuk...@stoo.me.uk>
Subject Andrew Johnson's comments
Date Wed, 09 Dec 2009 18:51:54 GMT
Hi,
     Here are Andrew Johnson's comments (adjusted for context). The 
grammar and spelling errors have been corrected already.
I'll correct the doc when there are undistib

I'll do this by page. Comments to follow in separate email.
Each number is listed like (1)., (2)., etc.

Chapter 3
=========

Page 7
======

Lists
-----

(1).

Instead of:
     List<ManagedRuntime> ImageProcess.getRuntimes()
Do we need:
     List<? extends ManagedRuntime>
- would allow List<PHPJavaRuntime> getRuntimes()

-----

(2).

Does List equality hold?

E.g. heap.getObjects().equals(heap.getObjects()

-------
(3).

Which methods returning lists throw exceptions?

-------

(4).

Predictable order via different VMs?

Chapter 6
=========
Page 24
=======

(5).

Please have method as page header/footer.

(6).

Walk GC graph using JSR 326.

References:   \/---------------------------\
     JavaObject        \                    |
     JavaClass         |                    |
     JavaStackFrame    }- getReferences() getTarget()
     JavaThread?       |
     JavaClassLoader?  / <-----------------getSource()

Have interface for classes having getReferences.

Page 25
=======
(7).

re. `services directory'
. This text file should contain a single line which is the package 
qualified name of the ImageFactory....
                                   ^^^^^^

Multiple factories?
How would multiple factories work in one jar?

(8).

re. Table 6.3 FactoryRegistry Methods

public Iterator FactoryRegistry.iterator()
Iterator<ImageFactory> or List?

(9).

public ImageFactory getFactories()

should be:

public ImageFactory[] getFactories()


(10).

FactoryRegistry.getFactories()

Returns the factories in the registry as an array

Copies?

(I presume Andrew means that the array is mutable without ill effect)

(11).

public Image getImage(File file)

Throws
IllegalArgumentException if file is null

Why not throw NPE?

(12).

List<ImageFactory>   sniff file type!

get suggested factories for a file or files:

/ getFactories(File file)
\ getFactories(File file, File file)

package javax.tools.diagnostics.image
======================================
Page 27
=======

(13).
Choose a better order to list the classes.

e.g. ImageFactory, Image, ImageAddressSpace, ImagePointer, ImageSection

(14).

Table 6.4. Interface Summary

Image - This class represents an entire operating system image (e.g. ??

The text after "(e.g." is completely missing.

(15).

Table 6.5. Class Summary

DataUnavailable should be DataUnavailableException


DU extends DUE?

Page 28
=======

(16).

interface ImageModule
--> running header

(I guess Andrew means that the header for the page should have the name 
of the interface.

Table 6.6
=========
(17).
     public List getSymbols()

should be

     public List<ImageSymbol> getSymbols()

(The API has generics added now to the Image API. However, the document 
generation needs to be modified.
  I won't add any further comments about it.)

Page 29
=======

Table 6.7. ImageMethods

getAddressSpaces()

     Also segmented arch?

Page 30
=======

getProcessorCount()

Returns the number of CPUs running in the system on which the image was 
running.

     System = partition?

(I guess Andrew is suggesting "System" should be described as a 
"partition" in a virtual machine, z/Arch LPAR, pSeries LPAR, etc.?)


I'll continue from page 31 soon.


Regards,
     Stuart


-- 
Stuart Monteith
http://blog.stoo.me.uk/


Mime
View raw message