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

Reply via email to