Hi Jean,
Thank you for reviewing the document. Please see my responses inline.
On 06/08/10 18:47, [email protected] wrote:
Karen,
Here's my comments. Some are just grammar but I didn't think you'd mind.
1 Purpose
----------------
line 1: OpenSolaris proves the an interactive graphical...., an
interactive text....,
2nd paragraph: These different installation applications are different
user interfaces and experiences to achieve the same
end goal: install OpenSolaris on the system.
2nd paragraph: The text installer uses a simple Python function that
calls the various functions and commands. The DC uses a python based
object to drive the image building process called the finalizer engine.
Fixed all of above.
2 Overview
------------------
paragraph 3: In addition to driving the installation process, the
engine also initializes the DataObjectCache and sets up the
InstallLogger. Both services are to be used by all install components.
Fixed.
3 Assumptions and Dependencies
---------------------------------------------------------
bullet 2:
The Data Object Cache is a singleton. All components access the
DataObjectCache directly without going through the engine. The engine
initializes the DataObjectCache. No other components should
initialize the DataObjectCache. ----- I'm wondering if that should be
something more forceful, like "No other components are allowed to
initialize the Data Object Cache."
Now that the Data Object Cache is no longer going to be a singleton. the
engine will instantiate the
DOC, and provide an interface for checkpoints to access the DOC.
I will remove this bullet point.
bullet 3: ditto
This is still under discussion. If we do decide that the logger will
not be a singleton, I will change the
statement to be more forceful like you suggested.
bullet 4: I think saying the engine executes the checkpoints might be
better wording?
Changed as suggested.
Applications that want to monitor progress should register one or more
progress receivers with the logger. Checkpoints report their progress
directly to the logger. The engine helps to normalize the progress
information for the logger. The install logger publishes progress
information received from the checkpoints to all registered progress
receivers.
Page 5
bullet at the top: Some engine features require functionality from
the DataObjectCache and the InstallLogger. Details on which features
from these components are used, and how they will be used will be
discussed later in this document.
Changed as suggested.
4 Programming Language
--------------------------------------------
C++ section: s/complied/compiled
Changed.
5 Checkpoints
------------------------
The installation engine does not have knowledge about the
functionality implemented in each checkpoint.
Changed as suggested.
5.1 Using checkpoints with the engine
-----------------------------------------------------------------
To register a checkpoint, the application provides a unique name for
the checkpoint, the path to the module that contains the checkpoint
class, the name of the checkpoint class, and any arguments needed for
instantiating the checkpoint.
Changed as suggested.
Requiring the application to provide a unique name for the checkpoint
allows different instances of the same checkpoint object class to be
used in the same
application.
Changed as suggested.
page 6
5.2 AbstractCheckpoint Class
--------------------------------------------------
All checkpoints registered into the engine are required to be a
subclass of the AbstractCheckpoint class.
The AbstractCheckpoint class is an abstract base class (ABC) in Python.
Changed as suggested.
6 Installation Engine
-----------------------------------
Applications generally interact with the engine to perform the
following one or more times during the
installation process.
Changed as suggested.
I would remove Application from each of the bullets since you've
already stated that above. Also the bullets should be made the same
tense. i.e. Instantiate, Register, Request.
Good suggestion, changed as suggested.
page 7
6.1 Singleton
------------------------
Do you mean the engine object should be instantiated by the
application and not initialized? (and in other parts of this paragraph)
Yes, I meant to say instantiated. Dermot also pointed out this. I have
gone through the whole document and made
all the needed changes.
6.3 Checkpoint registration
------------------------------------------------
s/initialized/instantiated
Changed.
page 8
6.3.1 Dynamic code execution
---------------------------------------------------
paragraph 1: At execution time, the engine imports the specified
module and initializes the specified checkpoint object.
paragraph 3: The user is not allowed to randomly add checkpoints for
these type of
applications.
... sure that a checkpoint with a given name actually refers to the
same checkpoint object implementation.
Changed all of above.
6.3.2 Ordering of registered checkpoints
----------------------------------------------------------------------
If a position is explicitly specified, the engine ensures that all
checkpoints
subsequent to the to-be-registered checkpoint have not been executed.
For example, if checkpoints a, b, c, d are registered, and checkpoints
a, b, c have been executed, it is not allowed to register a checkpoint
in front of 'c', but placing a checkpoint after 'c' is allowed.
Changed.
page 9:
6.4 Execution of checkpoints
-------------------------------------------------
The application requests.....
Changed.
2nd paragraph:
The engine first initializes all the checkpoints to be executed, then
calls the get_progress_estimate() function on each of the checkpoints.
Finally it runs the execute() function for each of the checkpoints.
Changed the grammar as suggested. Also changed "The engine first
initializes..." to "The engine first instantiates...."
page 10:
6.4.2 Running checkpoints
----------------------------------------------
Despite the fact that the checkpoints are executed in a different
thread, the execute_checkpoint() function does not return until all
checkpoints are executed or one checkpoint fails.
Changed as suggested.
page 11:
6.5 Cancel executing checkpoint
---------------------------------------------------------
Then, the engine waits for the execute() function of that checkpoint
to return. If a checkpoint chooses to not do anything when the
cancel() function is called, the engine will
not enforce a timeout, and kill the checkpoint by force. It will
simply wait till that particularcheckpoint's execute() function
completes.
Changed as suggested.
Comment: Couldn't this result in a hang? Can you explain why this
method was chosen?
This will result in a hang if the execute() function never returns or if
the cancel() function never returns, but
those functions are not supposed to hang.
This method is chosen because there's no way in python to forcefully
kill a thread. So, we need to
wait for the thread to stop itself.
page 14:
7.3.2.2 Getting the list of resumable checkpoints
-----------------------------------------------------------------------------------
For an application that terminates...
Changed as suggested.
That's it for tonight. I'll start at 7.4 Implementation tomorrow.
Thank you again for reviewing in detail and catching all the typos and
grammatical errors.
--Karen
_______________________________________________
caiman-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/caiman-discuss
