qpid-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Stitcher <astitc...@redhat.com>
Subject Heads-up: Splitting proton-c into multiple libraries [Was: Proton's road ahead]
Date Fri, 11 Nov 2016 16:46:16 GMT
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:

The github PR is:

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
   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
- 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
- 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:

This has turned out to be far longer than I intended - I hope it is clear enough. Comments,
criticisms etc. all welcome.


To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org

View raw message