[cap-talk] Last Call for ref_send API 1.0

David Wagner daw at cs.berkeley.edu
Mon Apr 2 16:12:13 CDT 2007

Tyler Close writes:
>...last chance to gripe about the names and patterns used in the API...

Works for me.  I have no gripes about anything in org.ref_send*.

I wrote down some minor comments below.  I believe they can all be
added later, either because they are backwards-compatible changes or
because they are Javadoc changes or because they only affect the
org.joe_e* libraries, so they may not be important now, but I wanted
to write them down while they were fresh in my mind.


Record: The Javadoc calls this "A pass-by-construction object.", but
I think you mean "An allegedly pass-by-construction object." -- is that
correct?  (Nothing enforces that this Record instances are indeed
pass-by-construction; it's up to the programmer to manually respect
the semantics of pass-by-construction objects.  Recipients of a Record
object should not rely upon it to be pass-by-construction.)

@cacheable: Do you mean "an allegedly cacheable property"?


Given the comments in Var's Javadoc, would it be useful to provide
a class that acts as a sensory facet to a Var (or other mutable Volatile)
that only provides authority to read the Volatile?  Something like:

    public final class VolatileFacet<T> implements Volatile<T> {
        private final Volatile ref;
        public VolatileFacet(T value) { ref = value; }
        public T cast() { return ref.cast(); }

Then the suspect code mentioned in Var's Javadoc could be conveniently
re-written as follows, if the intent was to provide only read-only access
to the balance:

    public Volatile<Integer> getBalance() {
        return new VolatileFacet(balance);

I don't know if "VolatileFacet" is the best name.  Of course, adding
such a class is a backwards-compatible change, so doesn't need to be
done now.

Resolved: The Javadoc for ref() doesn't say whether the caller can rely
upon the return value to be a trustworthy Resolved promise that resolves
to "value" (the argument to ref()).

I have no idea what detach() is doing, so it is hard for me to know
whether this is the best name.  At a minimum, it needs to be documented
better.  (For instance, how does it differ from ref()?)  Do I get to
reserve the right to gripe about detach()'s name once I understand what
it is doing? :-)

Eventual: The Javadoc at the top is very, very nice.

I don't understand what ready() is doing, or what is meant by
"the underlying reference implementation".  What is a "reference
implementation"?  Does it mean some sample implementation that the
ref-send library provides?  Also, what can the caller assume about the
Volatile returned by ready()?  Is it guaranteed to be trustworthy, to
only resolve once, etc.?  I do not understand the example for ready():
what does it mean to register an observer on an immediate value with type
"Account"?  When does the observer get invoked?  Under what conditions
would the result of applying ready() to an immediate reference cause
the resulting Volatile to be rejected?

I didn't understand the Javadoc for cast(), what cast() is doing,
what the purpose of the "expected" argument is for, or what proxy
the Javadoc is referring to.  Would more explanation help?  Would an
example help?

The documentation should probably specify what is meant by an
"allowed proxy type", or link/refer to the appropriate specification
in the Java class library documentation.

org.ref_send.promise.eventual.Loop: Ok, I admit I may not know how
to parse Java generics correctly.  Does the name "Task", in the defn
of the Loop interface, refer to a generic type parameter, or does it
refer to org.ref_send.promise.Task?  I'm guessing it is the former.
If so, that is incredibly confusing.  Standard Java convention is to use
one-letter capital letters for generic type parameters.  It's even worse
to make the name of a generic type parameter be the same as the name of
a public class/interface defined elsewhere in your API.  I suggest that
you change the defn of Loop to either

    public interface
    Loop<T extends Closure<Void,?>> extends Closure<T,Void> {
        Void post(T closure);

or to 

    import org.ref_send.promise.Task;

    public interface
    Loop extends Closure<Task,Void> {
        Void post(Task task);

according to your intent.  I'm guessing you intended the former, so the
change should be backwards-compatible, but please check for yourself.

org.joe_e.Keeper: The name "Keeper" doesn't mean anything to me.
It sounds like a generic concept, but org.joe_e.Keeper is used for a
very narrow purpose.  It would be a shame to take up a name that might
profitably be better used for something else, and it might be nice if
the name here was more evocative.  How about "ErrorHandler"?

org.joe_e.crypto.AES: Out of curiousity, why does this need to be in
the org.joe_e namespace?  Is AES something that pure Joe-E code cannot
implement?  Or is this an optimized implementation that uses native
methods or something?


list() shouldn't throw NullPointerException when the argument isn't a
directory.  Use some other exception.  Only throw NullPointerException
when the argument is null.  I guess this is not a backwards-compatible
change, so it needs to be done now.

name() should document that the "child" argument must be a single
filename component, not a relative path.  For instance, "../foo" or
"foo/bar" are right out.

vet() should document whether it is intended to be applied to a single
filename component, a relative path, and/or an absolute path.  Also,
I couldn't extract what the second sentence in the Javadoc for vet()
is trying to convey, though I suspect it is related.

org.joe_e.reflection.Reflection: I have reservations about the semantics
of some of the methods.  I feel like it would be beneficial to have
more discussion before it is ready to be inserted into a Joe-E library
which Joe-E promises to support forever.  Your choices may be fine for
users of ref-send, but for what goes into Joe-E libraries, I think the
question has to be about what is right for all Joe-E users.

org.ref_send.list.List: I'm curious about why you named the method
"getSize()" rather than "size()", as the latter seems to be the standard
name used by the Java collections classes.  Have you considered making
this implement java.util.List?  I suspect you have and decided it was
overkill.  Also, remind me some day to ask you why you added this class
rather than, say, java.util.LinkedList.

org.ref_send.promise.{curry,test}.*: I didn't look at any of this.
(I got tired.)

More information about the cap-talk mailing list