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
