Re: Proton engine api naming proposal
On Wed, 3 Oct 2012, Justin wrote: On Wed, 3 Oct 2012, Rafael Schloming wrote: I believe the convention I'm following is actually the norm (for a good reason). The get/set_foo pattern is used for passive slots, i.e. it's a strong signal that if you call set_foo with a given value then get_foo will return that same value until set_foo is called again. Whereas dynamic/computed/derived values (something where it would never make sense to have a setter) are generally not prefixed by get. Some examples in Java would be things like Collection.size(), Object.hashCode(), Map.values(). I think this is a pretty valuable convention as it is a signal that I agree that's a common convention in java. It's not the norm: counterexamples are Thread.getState(), Integer.getInteger(s), File.getFreeSpace(). In any case, it's arguably a good convention. It has one particular practical problem, more collisions. This problem is exhibited right now in pn_link_drained. What does that do? It *looks like* it is a dynamic predicate, but it isn't. If in the future you want to add such a predicate, you'll have a collision. _get_ keeps things cleanly separated. (In the case of pn_link_drained, I think that just needs a better name.) I'm pleased we're discussing this. Can we discuss it (and all the other things worth discussing, imo) before we set down changes in the code? I've updated the proposal again. I've also adjusted the Java naming to match the C naming in the main. Of course, they needn't work the same necessarily, but for instance, I figured that if we're going to distinguish between computed/derived and passive attributes in C, we ought to as well in Java. Justin
Re: Proton engine api naming proposal
On 4 October 2012 23:56, Justin Ross jr...@redhat.com wrote: On Wed, 3 Oct 2012, Justin wrote: On Wed, 3 Oct 2012, Rafael Schloming wrote: I believe the convention I'm following is actually the norm (for a good reason). The get/set_foo pattern is used for passive slots, i.e. it's a strong signal that if you call set_foo with a given value then get_foo will return that same value until set_foo is called again. Whereas dynamic/computed/derived values (something where it would never make sense to have a setter) are generally not prefixed by get. Some examples in Java would be things like Collection.size(), Object.hashCode(), Map.values(). I think this is a pretty valuable convention as it is a signal that I agree that's a common convention in java. It's not the norm: counterexamples are Thread.getState(), Integer.getInteger(s), File.getFreeSpace(). In any case, it's arguably a good convention. It has one particular practical problem, more collisions. This problem is exhibited right now in pn_link_drained. What does that do? It *looks like* it is a dynamic predicate, but it isn't. If in the future you want to add such a predicate, you'll have a collision. _get_ keeps things cleanly separated. (In the case of pn_link_drained, I think that just needs a better name.) I'm pleased we're discussing this. Can we discuss it (and all the other things worth discussing, imo) before we set down changes in the code? I've updated the proposal again. I've also adjusted the Java naming to match the C naming in the main. Of course, they needn't work the same necessarily, but for instance, I figured that if we're going to distinguish between computed/derived and passive attributes in C, we ought to as well in Java. So... personally I don't have quite the horror of extra characters that certain others do... and I think prepending an is on methods that are returning a boolean is a reasonable deviation from the pattern established in the C. I can buy that there are certain methods where the get/set pairing doesn't really imply the actual semantics that the methods have. In general for the count type variables that cannot directly be set, I think getXxxCount() also works, but I'm also happy with the current xxx() style. There are a couple of areas where I think the naming definitely needs work, in particular hostname: The local hostname is actually the hostname that is desired to be chosen at the remote endpoint, while the remote hostname is the hostname that the remote endpoint desires at the local side. Of the proposals, I think Delivery.update is less wrong than acknowledge ... the update may not be an acknowledgement but some other form of state change. Also rescind_credit is not really the semantics of drain (if there are messages available then the peer should send them, not simply cancel the credit). Source and Target - currently the API is incomplete here - a proper definition of these types is needed which is why in the Java I've currently got these as Source/Target Address. The Source and Target types should be properly defined with APIs which allow for the setting of other attributes than just the address. -- Rob Justin
Re: Proton engine api naming proposal
On Wed, 3 Oct 2012, Rafael Schloming wrote: I believe the convention I'm following is actually the norm (for a good reason). The get/set_foo pattern is used for passive slots, i.e. it's a strong signal that if you call set_foo with a given value then get_foo will return that same value until set_foo is called again. Whereas dynamic/computed/derived values (something where it would never make sense to have a setter) are generally not prefixed by get. Some examples in Java would be things like Collection.size(), Object.hashCode(), Map.values(). I think this is a pretty valuable convention as it is a signal that I agree that's a common convention in java. It's not the norm: counterexamples are Thread.getState(), Integer.getInteger(s), File.getFreeSpace(). In any case, it's arguably a good convention. It has one particular practical problem, more collisions. This problem is exhibited right now in pn_link_drained. What does that do? It *looks like* it is a dynamic predicate, but it isn't. If in the future you want to add such a predicate, you'll have a collision. _get_ keeps things cleanly separated. (In the case of pn_link_drained, I think that just needs a better name.) I'm pleased we're discussing this. Can we discuss it (and all the other things worth discussing, imo) before we set down changes in the code? Justin
Re: Proton engine api naming proposal
On Wed, Oct 03, 2012 at 08:35:00AM -0400, Justin wrote: On Wed, 3 Oct 2012, Rafael Schloming wrote: I believe the convention I'm following is actually the norm (for a good reason). The get/set_foo pattern is used for passive slots, i.e. it's a strong signal that if you call set_foo with a given value then get_foo will return that same value until set_foo is called again. Whereas dynamic/computed/derived values (something where it would never make sense to have a setter) are generally not prefixed by get. Some examples in Java would be things like Collection.size(), Object.hashCode(), Map.values(). I think this is a pretty valuable convention as it is a signal that I agree that's a common convention in java. It's not the norm: counterexamples are Thread.getState(), Integer.getInteger(s), File.getFreeSpace(). Agreed. The above APIs were a legacy of the pre-standardized APIs IIANM. In any case, it's arguably a good convention. It has one particular practical problem, more collisions. This problem is exhibited right now in pn_link_drained. What does that do? It *looks like* it is a dynamic predicate, but it isn't. If in the future you want to add such a predicate, you'll have a collision. _get_ keeps things cleanly separated. (In the case of pn_link_drained, I think that just needs a better name.) I'm pleased we're discussing this. Can we discuss it (and all the other things worth discussing, imo) before we set down changes in the code? +1 I find APIs of the form pn_verb_object to be extremely expressive, making the source code much more readable. -- Darryl L. Pierce, Sr. Software Engineer @ Red Hat, Inc. Delivering value year after year. Red Hat ranks #1 in value among software vendors. http://www.redhat.com/promo/vendor/ pgp1c7v06PB1A.pgp Description: PGP signature
Re: Proton engine api naming proposal
On Thu, Sep 13, 2012 at 9:36 AM, Justin Ross jr...@redhat.com wrote:
On Thu, 13 Sep 2012, Ted Ross wrote:
I'm not crazy about the work-processing function names as they seem to
disregard the grammar. Should they not all be pn_connection_* functions?
I agree about this. I would definitely prefer to see pn_connection_* for
the connection-scoped work interfaces. I guess I thought I was pressing my
luck, :).
I think there actually already is a consistent rule here, it's just missing
from your grammar. Wherever there is a linked list of things, the API uses
the form:
pn_collection_head(pn_root_t)
pn_collection_next(pn_element_t_t)
I think this is better than trying to stick it all on the root or all on
the element or splitting it up between the two. For example I think
pn_work_head is better than pn_head_delivery as the latter gives you less
information. The fact that it is a delivery is already contained in the
type signature, and there are multiple lists of deliveries maintained by
the engine, so just knowing that it is a list of deliveries isn't
sufficient. Even scoping it to the connection is not terribly useful as
there may well be multiple lists of deliveries on the connection. The
relevant info here is that it is the head of the work queue, a concept that
we actually do (or should) explain at length (somewhere). I would argue
that the work queue is actually the relevant concept/noun here, it just
doesn't have it's own lifecycle since it is a component of the connection.
In Java or some other garbage collected language you might see the noun
expressed directly as an object, e.g.:
WorkIterator work = new WorkIterator(connection);
while (...) {
Delivery d = work.next();
}
This exact pattern of course is extremely cumbersome and inefficient in C
since you'd have to malloc an object just to iterate, so naturally you use
a linked list instead, but I think conceptually the noun still exists and
if we lose the noun from the name we are missing an important key to index
into the documentation.
--Rafael
Re: Proton engine api naming proposal
- Original Message -
On Thu, Sep 13, 2012 at 9:36 AM, Justin Ross jr...@redhat.com
wrote:
On Thu, 13 Sep 2012, Ted Ross wrote:
I'm not crazy about the work-processing function names as they
seem to
disregard the grammar. Should they not all be pn_connection_*
functions?
I agree about this. I would definitely prefer to see
pn_connection_* for
the connection-scoped work interfaces. I guess I thought I was
pressing my
luck, :).
I think there actually already is a consistent rule here, it's just
missing
from your grammar. Wherever there is a linked list of things, the API
uses
the form:
pn_collection_head(pn_root_t)
pn_collection_next(pn_element_t_t)
I think this is better than trying to stick it all on the root or all
on
the element or splitting it up between the two. For example I think
pn_work_head is better than pn_head_delivery as the latter gives you
less
information. The fact that it is a delivery is already contained in
the
type signature, and there are multiple lists of deliveries maintained
by
the engine, so just knowing that it is a list of deliveries isn't
sufficient. Even scoping it to the connection is not terribly useful
as
there may well be multiple lists of deliveries on the connection. The
relevant info here is that it is the head of the work queue, a
concept that
we actually do (or should) explain at length (somewhere). I would
argue
that the work queue is actually the relevant concept/noun here, it
just
doesn't have it's own lifecycle since it is a component of the
connection.
In Java or some other garbage collected language you might see the
noun
expressed directly as an object, e.g.:
WorkIterator work = new WorkIterator(connection);
while (...) {
Delivery d = work.next();
}
This exact pattern of course is extremely cumbersome and inefficient
in C
since you'd have to malloc an object just to iterate, so naturally
you use
a linked list instead, but I think conceptually the noun still exists
and
if we lose the noun from the name we are missing an important key to
index
into the documentation.
--Rafael
All great stuff. I guess I'm surprised there aren't at least 2 standard C
coding styles out there to choose from.
So from now on I'll refer to this style as Rossrafi.
Dude, I can't believe you're coding C like that. Why aren't you using
Rossrafi?
William
