[cap-talk] Last Call for ref_send API 1.0

Marc Stiegler marcs at skyhunter.com
Tue Apr 3 12:57:33 CDT 2007


I want to register agreement with Dean about the use of the term Channel,
though for a different reason. "Pair" immediately conveys at least a small
clue about what it going on. "Channel" only speaks to those who already know
what this stuff is -- the least important audience.

--marcs

On 4/2/07, Dean Tribble <tribble at e-dean.com> wrote:
>
> I'm delighted that Facet does not apear in the API :-).  The two other
> names I'd recommend changing:
>
> Closure is a very common concept that is only loosely reflected it the
> decalred interface.  I have a vague recollection that Java has an existing
> variant of Runnable that might do.  If not, perhaps just a naming convention
> that permits of functions with more an less than one argument would be
> sufficient ( e.g., Closure1 or Fn1).
>
> As for "Channel"...!  Just returning a struct of a Promise and a Resolver
> is a pretty measly purpose for polluting the term "Channel"!  I think the
> primary reason for that is the lack of multiple return values.  If so, then
> just defining Pair<T,U> would allow that pattern to appear in multiple
> places without needing to define a new term for every occurrence.
>
> Cheers!
> Dean
>
> On 4/2/07, David Wagner <daw at cs.berkeley.edu> wrote:
> >
> > 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.
> >
> >
> > org.ref_send:
> >
> > 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"?
> >
> >
> > org.ref_send.promise:
> >
> > 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?
> >
> >
> > org.joe_e.file.Filesystem:
> >
> > 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.)
> > _______________________________________________
> > cap-talk mailing list
> > cap-talk at mail.eros-os.org
> > http://www.eros-os.org/mailman/listinfo/cap-talk
> >
>
>
> _______________________________________________
> cap-talk mailing list
> cap-talk at mail.eros-os.org
> http://www.eros-os.org/mailman/listinfo/cap-talk
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.eros-os.org/pipermail/cap-talk/attachments/20070403/c91f10f5/attachment.html 


More information about the cap-talk mailing list