+1 - make it so! On Fri, 2016-11-11 at 11:46 -0500, Andrew Stitcher wrote: > A couple of weeks back Justin mentioned forward plans for proton. I > want to let everyone know what I've been working on recently to split > up the proton-c library and hopefully make its source tree layout a > bit > easier to follow. > > The JIRAs for this work are: > https://issues.apache.org/jira/browse/PROTON-1350 > https://issues.apache.org/jira/browse/PROTON-1351 > > The github PR is: > https://github.com/apache/qpid-proton/pull/87 > > I'll describe the final results of the rearrangement/split as the > best > way to approach this - I'll note the noticeable API changes at the > end. > > The re-organization introduces a core proton library called qpid- > proton-core (libqpid-proton-core.so). This contains only the protocol > processing engine of proton-c. These are the APIs included in the > following headers (with a few supporting headers). > > One of the defining feature of this library is that it is totally > portable with no OS dependencies at all. There are some compiler > (standard library) dependencies mostly due to MS Visual Studio not > supporting C99. > > - proton/engine.h > -- Convenience include for > --- proton/condition.h > --- proton/connection.h > --- proton/session.h > --- proton/terminus.h > --- proton/link.h > --- proton/delivery.h > --- proton/event.h > --- proton/transport.h > - proton/condition.h > -- pn_condition_t > - proton/connection.h > -- pn_state_t > -- pn_connection_t > - proton/delivery.h > -- pn_delivery_t > -- pn_delivery_tag_t > - proton/event.h > -- pn_event_t > -- pn_event_type_t > -- pn_collector_t > - proton/link.h > -- pn_link_t > -- pn_snd_settle_mode_t > -- pn_rcv_settle_mode_t > - proton/session.h > -- pn_session_t > - proton/transport.h > -- pn_transport_t > -- pn_trace_t > -- pn_tracer_t > > - proton/codec.h > -- pn_type_t > -- pn_atom_t > -- pn_data_t > - proton/disposition.h > -- pn_disposition_t > - proton/error.h > -- pn_error_t > - proton/message.h > -- pn_message_t > - proton/sasl.h > -- pn_sasl_t > -- pn_sasl_outcome_t > - proton/ssl.h > -- pn_ssl_domain_t > -- pn_ssl_t > -- pn_ssl_mode_t > -- pn_ssl_resume_status_t > -- pn_ssl_verify_mode_t > -- pn_ssl_cert_subject_subfield (! name not consistent with others) > -- pn_ssl_hash_alg (! name not consistent with others) > - proton/terminus.h > -- pn_terminus_t > -- pn_terminus_type_t > -- pn_durability_t > -- pn_expiry_policy_t > -- pn_distribution_mode_t > > Supporting headers: > - proton/types.h > -- Declares nearly all the types used in the APIs. It > is > included nearly everywhere to get these declarations. > -- Maybe it > should actually declare *all* of them. > - proton/type_compat.h > -- Used to > portably get stdbool/stdint and ssize_t types > - proton/import_export.h > -- > Used to portably handle API symbol export and hiding. > > - proton/object.h > -- This is not really part of the user API, and may only be needed > for > reactor based bindings. > -- [pn_object_t] (actually void*) > -- pn_handle_t > -- pn_shandle_t > -- pn_class_t > -- pn_string_t > -- pn_list_t > -- pn_map_t > -- pn_hash_t > -- pn_iterator_t > -- pn_record_t > - proton/cid.h > -- This is also part of the object system and again may only be > needed > for reactor based bindings. > -- pn_cid_t > > I'm not sure this is really a good core API at all. At least Proton > logging should be revisited and perhaps redesigned. > - proton/log.h > -- pn_logger_t > > The next set of APIs are "extras" - they are not included in the core > and are purely provided as conveniences. These may be bundled into > their own library qpid-proton-extra (libqpid-proton-extra.so) > - include/proton/parser.h > -- This contains a parser from a textual format to the proton-c > pn_data_t type. > - include/proton/url.h > -- This contains a parser that can dissect URLs used for specifying > connection and messaging addresses. > > The remaining part of the library is regarded as legacy and stays in > the existing qpid-proton library. > - include/proton/handlers.h > - include/proton/messenger.h > - include/proton/reactor.h > - include/proton/selectable.h > > These headers are for the messenger and reactor APIs. > > The existing proton library (qpid-proton/libqpid-proton.so) still > exists and still has the same content as before (Except for some APIs > that were really internal and have now been hidden away - see the > section at the end). > > The intention is that moving forward all the language bindings to > proton-c will be modified to only use the core APIs, with perhaps the > extra library used if necessary. This is already the case for the go > binding which has already been modified to only use core APIs. The > C++ binding is fairly close to only using the core APIs, but will > probably require the URL parser from the extras library. > > Other bindings will follow. > > The proton-c source tree organization has been simplified somewhat > and rearranged so that the different API sections described above map > directly to source tree directories. > > [Everything here is relative to the proton-c/src in the full source > distribution] > > Core library: All source in directories > - core - The actual proton-c engine > - compiler - Any compiler specific core (currently there is only MSVC > code here) > - sasl - The code supporting the SASL protocol layer. This code may > not > all be OS independent as it is used to interface an external > library > to proton. The default implementation of SASL is pure ANSI C. > > - ssl - The code supporting the ssl protocol layer. Again this code > is > not entirely OS independent as the optional schannel support is > Windows only. > > Extra (potential) library: All source in directory > - extra > > The legacy APIs are in the remaining directories: > - handlers > - messenger > - platform - This contains OS and compiler specific code for the > legacy > APIs. > - reactor > - reactor/io - This contains io implementations for the reactor and > messenger APIs. > > For the moment the installed header files have not been rearranged in > the source tree, although it may be a good idea for some future work > to separate them by category. > > These changes shouldn't be noticeable to anyone using the current > qpid-proton library is it is more-or-less unchanged. The "more-or- > less" has a little detail though: I have moved a few previously > exposed APIs to be internal only - they are not used by any example > and logically aren't needed. but it is possible that someone > somewhere is using them. > > These are: > proton/io.h > proton/selector.h > proton/scanner.h > > This has turned out to be far longer than I intended - I hope it is > clear enough. Comments, criticisms etc. all welcome. > > Andrew > > --------------------------------------------------------------------- > To unsubscribe, e-mail: users-unsubscr...@qpid.apache.org > For additional commands, e-mail: users-h...@qpid.apache.org >
--------------------------------------------------------------------- To unsubscribe, e-mail: users-unsubscr...@qpid.apache.org For additional commands, e-mail: users-h...@qpid.apache.org
