www.digitalmars.com         C & C++   DMDScript  

c++.stlsoft - Proposal: (minor) changes to Back-end architecture to facilitate versioning

Hi

Several recent feature requests - including
http://sourceforge.net/forum/forum.php?thread_id=2991691&forum_id=475313,
http://sourceforge.net/forum/forum.php?thread_id=2807774&forum_id=475313 - have
involved non-trivial changes/enhancements to one or
more back-ends.

I am very keen to stop the beta-train - we're now at 1.0.1 beta 183! - and
actually produce a final release. But one of the criteria
for this is that the 1.0 final is a stable base on which new functionality can
be added with minimal, preferably zero, backwards
incompatibilities.

It's occured to me that one option for satisfying all these requirements is to
version the individual back-end libraries, perhaps
via a version member of their initialisation structures. For example,
pan_be_syslog_init_t would go from this:

struct pan_be_syslog_init_t
{
    pan_uint32_t    flags;
    pan_uint32_t    options;
    pan_uint8_t      facility;

#ifdef __cplusplus
    pan_be_syslog_init_t();
#endif /* __cplusplus */
};

to this:

struct pan_be_syslog_init_t
{
    pan_uint32_t    version; /* ** */
    pan_uint32_t    flags;
    pan_uint32_t    options;
    pan_uint8_t      facility;

#ifdef __cplusplus
    pan_be_syslog_init_t();
#endif /* __cplusplus */
};


The rule would be that the version member must be set from PANTHEIOS_VER, and
this would be provided automatically by all the
pantheios_be_XXXX_getDefaultAppInit() function(s). That way, the implementation
of the back-end could provide reasonable behaviour
even in the case where the application code was not recompiled, but merely
linked to a newer version of Pantheios wherein a
particular back-end had changed. Thus, the responsibility would fall, as it
should, on the implementor the back-end to ensure that
backwards-compatibility is maintained. For example, say that a future version
of be.syslog - say, with version 1.1 of Pantheios -
wants to incorporate a function pointer into the structure, this would be done
as follows:

struct pan_be_syslog_init_t
{
    pan_uint32_t    version; /* ** */
    pan_uint32_t    flags;
    pan_uint32_t    options;
    pan_uint8_t      facility;
    void (*pfn)();

#ifdef __cplusplus
    pan_be_syslog_init_t();
#endif /* __cplusplus */
};

The implementation of be.syslog would check the version number on the
structure. If < 0x01010000, then the pfn would be missing, and
a default value (e.g. NULL) would be assumed; otherwise, the pfn given in (the
latest version of) the structure would be used.

I believe that this would account for the request to allow user-supplied
formatting for stock back-ends - via a format function
pointer, perhaps - and also the increasing enhancements that are likely with
be.file in the near future.

I'd be keen to hear others' thoughts on the matter.

Matt
Feb 15 2009