On Thu, Jan 29, 2015 at 9:28 AM, Justin Ross <justin.r...@gmail.com> wrote:
> This makes good sense on its own, but it doesn't help with our goal of > naming and grouping together a "growable library of like things". In other > words, if we end up with many reactor implementations, it won't be very > approachable to have them littered around as dissimilar peers to reactor.h. > I don't think it's really workable to think of C header files as simple analogs to python packages. C header files need to first and formost correspond to the C symbols they include. Breaking that correspondence does a huge disservice to the usability of the API from C. Beyond that, the fact that C doesn't actually have packages and has just one global namespace really forces you to use flatter naming for your C symbols since everytime you type a symbol, you need to type out its full global name. These two things together pretty much guarantee that the C header files can't match python package names unless you force everyone to type out the full python package name as part of every C symbol. The one sortof exception to this is grouping header files which include a bunch of commonly used stuff together, e.g. we have proton/engine.h connection, session, link, delivery, etc, since they are all often used together. It's not quite right to think of this as a python package either though because it doesn't actually introduce any namespacing. It's really just an alias for a bunch of common includes. If you want to improve approachability, doxygen has lots of tools for defining groups and organizing/presenting otherwise flat APIs in a more structured way. This is because the whole large flat C API is pretty common, so generally it is organized with annotations in the doc tags that doxygen then uses to create things that actually are more analogous to python packages. This used to be set up, I'm not sure if it still is, but I would suggest that this is probably the first place to look to start improving accessibility. I assume this is why you have handlers.h: so you don't need to define a > header file for each handler implementation. Down the line, we could add a > reactors.h, but then we have reactor.h and reactors.h--not good. > The difference here is that you can't use multiple reactors simultaneously, so it will never make sense to have a reactors.h. Whereas the handlers are much more tightly coupled and they are expected to be intermingled with each other. Also, these handlers aren't very configurable, so the extent of the API is just one constructor. If we develop a more complicated handler, e.g. pn_foo_t, with a lot of pn_foo_* methods, I would expect it to go into proton/foo.h (and possibly be included from handlers.h for convenience.) > We could address the concern through directory structure or perhaps through > a naming convention: reactor.h with reactor_$variant.h. The latter pattern > seems to be relatively common. > This would either break the mapping between header files and symbols, or require unusably long symbol names. > I find types.h strange against all of this. Are the endpoint types > collected there in order to solve a dependency problem? It contains some > but definitely not all of the non-amqp-datatype types. > Yes, it is to solve a dependency problem. --Rafael
