----- Original Message ----- > On Thu, Sep 13, 2012 at 9:36 AM, Justin Ross <[email protected]> > 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
