February 15, 2009
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