[Vortex] CHANGE-NOTIFICATION: vortex-ctx-api-01
Francis Brosnan Blazquez
francis at aspl.es
Tue Jan 22 10:27:14 CET 2008
#####################################
#### Change notification ####
#####################################
Change Id: vortex-ctx-api-01
Project name: Vortex Library 1.1 series
Included in: already included and to be shipped with next stable
release 1.1.0
Status: NOTIFY
Author: Francis Brosnan Blázquez
Motivation
~~~~~~~~~~
The proposed changes will provided an API that will make the library
full stateless, storing the context into a single reference owned by
the application caller. The change introduced is large enough to start
a new branch to protect applications in production developed until
now with the 1.0 series.
The main advantage that will provide the change is the ability to
create several running and independent context inside the same
process. This is not only a more general API approach but also
provides better portability results because the state required by the
library for its proper function do not depends on the way the OS loads
the application into memory.
Change Description
~~~~~~~~~~~~~~~~~~
The following set of function have been removed from the 1.1 series,
replaced by a new version:
1. Initialization:
- vortex_init
- vortex_exit
Replaced by:
- vortex_init_ctx
- vortex_exit_ctx
2. Internal context handling from previous release
- vortex_ctx_set (no longer exists, conceptually not required)
- vortex_ctx_get (no longer exists, conceptually not required)
3. Functions updated (same function name, which now includes a new
parameter "ctx").
[log activation]
- vortex_log_is_enabled
- vortex_log2_is_enabled
- vortex_log_enable
- vortex_log2_enable
- vortex_color_log_is_enabled
- vortex_color_log_enable
[environment conf]
- vortex_conf_get
- vortex_conf_set
[general support to find files and local data]
- vortex_support_add_search_path
- vortex_support_add_search_path_ref
- vortex_support_add_domain_search_path
- vortex_support_add_domain_search_path_ref
- vortex_support_find_data_file
- vortex_support_domain_find_data_file
[vortex connection module]
- vortex_connection_new_empty
- vortex_connection_new
- vortex_connection_timeout
- vortex_connection_connect_timeout
- vortex_connection_get_timeout
- vortex_connection_get_connect_timeout
- vortex_connection_notify_new_connections
- vortex_connection_set_auto_tls
- vortex_connection_sanity_socket_check
[vortex listener module]
- vortex_listener_new
- vortex_listener_new2
- vortex_listener_new_full
- vortex_listener_wait
- vortex_listener_set_on_connection_accepted
- vortex_listener_parse_conf_and_start
- vortex_listener_set_default_realm
- vortex_listener_get_default_realm
[vortex frame factory]
- vortex_frame_create
- vortex_frame_create_full
- vortex_frame_create_full_ref
[vortex greetings module]
- vortex_greetings_get_features
- vortex_greetings_set_features
- vortex_greetings_get_localize
- vortex_greetings_set_localize
[vortex profiles module]
- vortex_profiles_register
- vortex_profiles_unregister
- vortex_profiles_set_mime_type
- vortex_profiles_get_mime_type
- vortex_profiles_get_transfer_encoding
- vortex_profiles_register_extended_start
- vortex_profiles_is_defined_start
- vortex_profiles_is_defined_close
- vortex_profiles_is_defined_received
- vortex_profiles_get_actual_list
- vortex_profiles_get_actual_list_ref
- vortex_profiles_registered
- vortex_profiles_is_registered
[vortex io module]
- vortex_io_waiting_use
- VortexIoCreateFdGroup (handler)
- vortex_io_waiting_get_current
- vortex_io_waiting_set_create_fd_group
- vortex_io_waiting_set_destroy_fd_group
- vortex_io_waiting_set_clear_fd_group
- vortex_io_waiting_set_add_to_fd_group
- vortex_io_waiting_set_is_set_fd_group
- vortex_io_waiting_set_have_dispatch
- vortex_io_waiting_set_dispatch
- vortex_io_waiting_set_wait_on_fd_group
[vortex reader]
- vortex_reader_allow_msgno_starting_from_1
[vortex thread pool]
- vortex_thread_pool_new_task
- vortex_thread_pool_get_running_threads
- vortex_thread_pool_set_exclusive_pool
[vortex sasl module]
- vortex_sasl_set_external_validation
- vortex_sasl_set_external_validation_full
- vortex_sasl_set_anonymous_validation
- vortex_sasl_set_anonymous_validation_full
- vortex_sasl_set_plain_validation
- vortex_sasl_set_plain_validation_full
- vortex_sasl_set_cram_md5_validation
- vortex_sasl_set_cram_md5_validation_full
- vortex_sasl_set_digest_md5_validation
- vortex_sasl_set_digest_md5_validation_full
- vortex_sasl_accept_negociation
- vortex_sasl_accept_negociation_full
[vortex tls module]
- vortex_tls_is_enabled
- vortex_tls_set_default_ctx_creation
- vortex_tls_set_default_post_check
- vortex_tls_accept_negociation
[vortex xml-rpc module]
- vortex_xml_rpc_accept_negociation
- vortex_xml_rpc_listener_parse_conf_and_start_listeners
[vortex errno module]
- vortex_errno_show_error
- vortex_errno_show_last_error
[vortex tunnel module]
- vortex_tunnel_settings_new
- vortex_tunnel_settings_new_from_xml
- vortex_tunnel_accept_negotiation
- vortex_tunnel_set_resolver
Solution to incompatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~
In general, the API change introduced affect all functions that have
the ability to change the state of the current library instance
loaded. Because this, and the fact that the library is now stateless,
a VortexCtx instance is required to perform such configuration.
However, not all functions requires a VortexCtx instance. This is
because main objects inside the Vortex API like VortexConnection,
VortexChannel or VortexFrame hold a reference to the VortexCtx that
was used to create them. This has allowed to minimize the API update
for those functions receiving as parameter some of these types.
According to this, the following function will be useful to get the
context for future operations, having a reference to a connection,
channel or frame:
- vortex_frame_get_ctx
- vortex_connection_get_ctx
- vortex_channel_get_ctx
Additionally, this also has allowed to not change any handler
definition. This will make current handlers written with 1.0 series to
be reusable with 1.1 series.
Special mention to initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following will be required to properly initialize the library:
VortexCtx * ctx;
/* create an empty context */
ctx = vortex_ctx_new ();
/* init the context and start vortex library execution */
if (! vortex_init_ctx (ctx)) {
/* handle error */
return -1;
}
/* do useful work */
/* stop the vortex library execution (for this particular ctx) */
vortex_exit_ctx (ctx, true);
Special mention to library compilation and its usage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Applications using Vortex Library 1.1 API will still use the following
include to use its services:
#include <vortex.h>
As a standard location recommendation, the following will be used to
locate the vortex library headers:
../include/vortex/vortex.h Vortex Library 1.0
vortex_types.h
....
../include/vortex-1.1/vortex.h Vortex Library 1.1
vortex_types.h
....
In this context, it is encourage package maintainers use the following
include flags according to the vortex revision used:
-I../include/vortex Vortex Library 1.0
-I../include/vortex-1.1 Vortex Library 1.1
The linker flag to use will change because the library will be
available in the following form:
libvortex-1.1.dll (windows)
libvortex-1.1.so (unix platforms)
This will require to use the following linker flag to get access to
services provided by 1.1 series:
-lvortex-1.1
In the same direction, those users taking advantage of pkg-config
configuration system, will have to update its autoconf voodoo to:
PKG_CHECK_MODULES(VORTEX, vortex-1.1 >= 1.1.0)
which is the same:
pkg-config --libs --cflags vortex-1.1
About two branches
~~~~~~~~~~~~~~~~~
>From ASPL there is no especial plans to kill the 1.0 branch at some
particular time.
Our intention, taking into consideration our current professional
support contracts, is to keep running and updated the branch 1.0,
integrated changes from 1.1 (and viceversa), as long as it is
technically possible.
As long as both branches provides a useful API and attractive
alternative to programmers, they will be maintained.
With the time, this will reviewed to take a decision.
However, it is advised that our main effort will be focused in the new
branch.
References
~~~~~~~~~~
[1] Project link:
http://vortex.aspl.es
[2] Change notification published by the project:
http://vortex.aspl.es/doc.html
[3] Change notification definition
http://www.aspl.es/change/change-notification.txt
--
Francis Brosnan Blazquez <francis at aspl.es>
Advanced Software Production Line, S.L.
More information about the Vortex
mailing list