You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@qpid.apache.org by Andrew Stitcher <as...@redhat.com> on 2016/11/11 16:46:16 UTC
Heads-up: Splitting proton-c into multiple libraries [Was: Proton's
road ahead]
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-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Heads-up: Splitting proton-c into multiple libraries [Was:
Proton's road ahead]
Posted by Andrew Stitcher <as...@redhat.com>.
On Mon, 2016-11-14 at 13:04 +0000, Adel Boutros wrote:
> Hello,
>
>
> What are the impact of these changes from a user point of view? Will
> the upgrade be automatic or will it require changes as was the case
> with the update from 0.12 to 0.14 for example?
These changes essentially don't change the user facing API at all:
- They only change the C code any other language bindings are not
affected at all.
- If you carry on using the old C library (libqpid-proton) then you
should have the same user facing API. This is not 100% true because
some very low level APIs have been removed, but it is vanishingly
unlikely anyone is using those.
- There is now a new "core" API that contains only the protocol
processing part of protn without any IO. This is intended to be used to
support language bindings and to form the basis for other APIs.
Andrew
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Heads-up: Splitting proton-c into multiple libraries [Was:
Proton's road ahead]
Posted by Adel Boutros <Ad...@live.com>.
Hello,
What are the impact of these changes from a user point of view? Will the upgrade be automatic or will it require changes as was the case with the update from 0.12 to 0.14 for example?
Regards,
Adel
________________________________
From: Andrew Stitcher <as...@redhat.com>
Sent: Friday, November 11, 2016 9:41:37 PM
To: users@qpid.apache.org
Subject: Re: Heads-up: Splitting proton-c into multiple libraries [Was: Proton's road ahead]
We could certainly copy the URL parser functionality into the C++
binding but as Ken notes it is used in the reactor so we'd have to
leave it there too (although we can make it private).
As for the parser for the pn_data_t I think that can be completely
removed as I'm not aware of any use of it all.
Andrew
On Fri, 2016-11-11 at 15:25 -0500, Ken Giusti wrote:
> IIRC C reactor also uses the url parser.
>
>
> ----- Original Message -----
> >
> > From: "Justin Ross" <ju...@gmail.com>
> > To: users@qpid.apache.org
> > Sent: Friday, November 11, 2016 3:02:40 PM
> > Subject: Re: Heads-up: Splitting proton-c into multiple libraries
> > [Was: Proton's road ahead]
> >
> > On Fri, Nov 11, 2016 at 8:46 AM, Andrew Stitcher <astitcher@redhat.
> > com>
> > wrote:
> > >
> > >
> > > Extra (potential) library: All source in directory
> > > - extra
> > >
> >
> > Could we avoid having this extra library if we copied the URL
> > parser to the
> > C++ binding? You noted elsewhere that the only other thing in
> > here, the
> > data parser, isn't currently used.
> >
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Heads-up: Splitting proton-c into multiple libraries [Was:
Proton's road ahead]
Posted by Andrew Stitcher <as...@redhat.com>.
We could certainly copy the URL parser functionality into the C++
binding but as Ken notes it is used in the reactor so we'd have to
leave it there too (although we can make it private).
As for the parser for the pn_data_t I think that can be completely
removed as I'm not aware of any use of it all.
Andrew
On Fri, 2016-11-11 at 15:25 -0500, Ken Giusti wrote:
> IIRC C reactor also uses the url parser.
>
>
> ----- Original Message -----
> >
> > From: "Justin Ross" <ju...@gmail.com>
> > To: users@qpid.apache.org
> > Sent: Friday, November 11, 2016 3:02:40 PM
> > Subject: Re: Heads-up: Splitting proton-c into multiple libraries
> > [Was: Proton's road ahead]
> >
> > On Fri, Nov 11, 2016 at 8:46 AM, Andrew Stitcher <astitcher@redhat.
> > com>
> > wrote:
> > >
> > >
> > > Extra (potential) library: All source in directory
> > > - extra
> > >
> >
> > Could we avoid having this extra library if we copied the URL
> > parser to the
> > C++ binding?��You noted elsewhere that the only other thing in
> > here, the
> > data parser, isn't currently used.
> >
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Heads-up: Splitting proton-c into multiple libraries [Was:
Proton's road ahead]
Posted by Ken Giusti <kg...@redhat.com>.
IIRC C reactor also uses the url parser.
----- Original Message -----
> From: "Justin Ross" <ju...@gmail.com>
> To: users@qpid.apache.org
> Sent: Friday, November 11, 2016 3:02:40 PM
> Subject: Re: Heads-up: Splitting proton-c into multiple libraries [Was: Proton's road ahead]
>
> On Fri, Nov 11, 2016 at 8:46 AM, Andrew Stitcher <as...@redhat.com>
> wrote:
> >
> > Extra (potential) library: All source in directory
> > - extra
> >
>
> Could we avoid having this extra library if we copied the URL parser to the
> C++ binding? You noted elsewhere that the only other thing in here, the
> data parser, isn't currently used.
>
--
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Heads-up: Splitting proton-c into multiple libraries [Was:
Proton's road ahead]
Posted by Justin Ross <ju...@gmail.com>.
On Fri, Nov 11, 2016 at 8:46 AM, Andrew Stitcher <as...@redhat.com>
wrote:
>
> Extra (potential) library: All source in directory
> - extra
>
Could we avoid having this extra library if we copied the URL parser to the
C++ binding? You noted elsewhere that the only other thing in here, the
data parser, isn't currently used.
Re: Heads-up: Splitting proton-c into multiple libraries [Was:
Proton's road ahead]
Posted by Andrew Stitcher <as...@redhat.com>.
Just to note that I have now merged this change into master, having
received no strong objections.
I did receive a comment that perhaps the new directory layout for some
of the legacy code isn't the best it could be, and I agree with this.
Specifically - that the "handlers" directory should really be a part of
the "reactor" directory as handlers are reactor API specific, also
since "io" is actually shared between the reactor and messenger APIs
maybe it should be at the top level.
In the interests of progressing I think we can make any further changes
here separately from this change.
Andrew
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org
Re: Heads-up: Splitting proton-c into multiple libraries [Was:
Proton's road ahead]
Posted by Alan Conway <ac...@redhat.com>.
+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-unsubscribe@qpid.apache.org
> For additional commands, e-mail: users-help@qpid.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@qpid.apache.org
For additional commands, e-mail: users-help@qpid.apache.org