Hi Darren,
On Tue, 6 Jul 2010, Darren Kenny wrote:
Hi Alok,
I took a quick look at the document, it looks good so far, not too many
comments, but I still have some ... :)
(I apologies in advance if you've already got some of these things planned)
General:
- Page numbers - it's really worthwhile putting in page numbers in the footer
in the form "x of y", especially for review feedback.
- References to classes, etc. in the text are hard to pick out - some have
quotes, some don't, and it's all in the same font. I would suggest applying
the "Source Text" style to each - which allows you to be consistent
throughout the document - and you can modify the style at any time and it'll
be applied throughout the document - e.g. change the f/g color...
I had meant to make some of these changes before submitting
the doc for official review. The latest doc has these updates
as well as a table of contents.
More specific, referencing section numbers:
Section 1.4:
- In the requirements you say that functionality should not regress, yet
later in the document some features are being removed - I think that it
would be clearer to say that opportunity will be taken to clean up some
features that are not heavily used, or are available in other ways - e.g.
the -R option, and UFS support.
Good idea, changed.
Section 2.2:
- There is no mention of the snapshot/roll-back functionality as a
dependency, it should probably be referenced.
Added.
Section 3.0:
- I wonder would a data-flow/process diagram be of benefit here in the
description of the order of how things are done.
I can add it if it would help explain the way DC would
work.
Section 3.3.x:
- For each of the checkpoints, I think that it's worth spelling out what
exactly the expected input should look like in the DOC, and also, if there
is any output to the DOC, what this would look like. Specifically I think
this is useful for people who would like to look at each checkpoint in
isolation - and possibly best for future re-use of any such checkpoint.
For example, this could be a DataObjectDict with specific name/value
parameters, or an instance of a specific class, and where this will be
stored in the DOC - probably we need a consistent way to state this, and
maybe a path (XPath style?) like:
/DOC/volatile/...
or
/DOC/**/my_cp_data
would be useful.
That's a great idea, it will also help flush out the specific
details for the various checkpoints and the DataObjects that
they will reference from the DOC.
Section 3.3.7:
- Calling TransferCPIO.execute to me seem to be the wrong thing to be doing.
I've said this to Jean recently too - there is no reason that TransferCPIO
needs to be ONLY a Checkpoint, it can just as easily, and I think more
correctly, export another API, which allows for it to be used outside of
the Engine/Checkpoint mechanism - in fact this would make writing unit
tests easier too - since this would most likely be the main API, with the
execute() method making use of it too.
Providing such an API also allows for customer-written finalizers to
make use of it too.
I agree. It is much cleaner to use a separate API that invokes
the needed functionality out of the context of the engine. This
change has been made in the doc I posted yesterday.
Section 3.5:
- I'm wondering if there is some benefit to providing a FinalizerCheckpoint
base-class for customer-written finalizers to sub-class, rather than
AbstractCheckpoint.
Firstly it would allow easy distinction of them, but it would also allow
us a little more control over what the implementor would need to write -
e.g. do we want them writing to/from_xml methods?
They won't have to implement the to_xml/from_xml methods
unless they're trying to do something very specialized.
I would argue that in most cases, if not all, most of
their needs would be met adequately by the DataObjectDict
class.
It would also allow us to minimize the need for the implementor to know
about the inner workings of CUD, and since they could access things using
class/instance methods which could abstract things for them.
How would providing a FinalizerCheckpoint class help in
that regard? It would seem to me that we could make it
just as easy for 3rd party implementors to write Checkpoints
with sufficient documentation and examples.
Thanks for the review, Darren.
Alok
_______________________________________________
caiman-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/caiman-discuss
