Re: [PATCH] tools/toollog: Drop XTL_NEW_LOGGER()

[Ian Jackson <Ian.Jackson@eu.citrix.com>]

Ian Jackson writes ("Re: [PATCH] tools/toollog: Drop XTL_NEW_LOGGER()"):
> Ian Campbell writes ("Re: [PATCH] tools/toollog: Drop XTL_NEW_LOGGER()"):
> > The underlying issue with all of these is the _undocumented_ nature of the
> > assumptions, which is certainly a bug, however those assumptions are not in
> > themselves "unreasonable" as was claimed.
> 
> Maybe I should submit a counter-patch providing documentation.

I think this macro is useful because if you wanted to write (say)
xtl_logger_syslog, you would want to use it to help you with some
boilerplate.

Ian.

>From f749eea51c35c787b8ca7514a21ac145e2946ff8 Mon Sep 17 00:00:00 2001
From: Ian Jackson <ian.jackson@eu.citrix.com>
Date: Tue, 19 Jan 2016 17:29:30 +0000
Subject: [PATCH] xentoollog: Document XTL_NEW_LOGGER convenience macro

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
---
 tools/libs/toollog/include/xentoollog.h |   53 +++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/tools/libs/toollog/include/xentoollog.h b/tools/libs/toollog/include/xentoollog.h
index 853e9c7..95f7482 100644
--- a/tools/libs/toollog/include/xentoollog.h
+++ b/tools/libs/toollog/include/xentoollog.h
@@ -113,6 +113,59 @@ void xtl_progress(struct xentoollog_logger *logger,
 const char *xtl_level_to_string(xentoollog_level); /* never fails */
 
 
+/*
+ * To use this macro:
+ *
+ *   Define your own logger struct, containing the vtable.
+ *
+ *       typedef struct {
+ *            xentoollog_logger vtable; // must come first
+ *            [ state your logger needs ]
+ *       } xentoolog_logger_mine;
+ *
+ *   Write the logging functions:
+ *
+ *       static void mine_vmessage([ see above ]);
+ *       static void mine_progress([ see above ]);
+ *       static void mine_destroy(struct xentoollog_logger *logger);
+ *
+ *   Write a constructor:
+ *
+ *       mine_xentoollog_logger *tl_createlogger_mine([whatever]) {
+ *           mine_xentoolllog_logger newlogger;
+ *
+ *           [ fill in fields of newlogger ]
+ *
+ *           return XTL_NEW_LOGGER(mine, newlogger);
+ *       }
+ *
+ *   If newlogger contains resources that might need to be released,
+ *   the constructor must check the return value from XTL_NEW_LOGGER:
+ *   if it is NULL, the constructor must release the resources.
+ *
+ *
+ * Formally:
+ *
+ *   xentoollog_logger_MINE*
+ *   XTL_NEW_LOGGER(MINE, xentoollog_logger_MINE contents);
+ *
+ *     Fills in contents.vtable.  Allocates a new struct.  Copies
+ *     contents into it.  Finally, returns a pointer to the copy.
+ *
+ *     If allocation fails, uses contents to report this failure, and
+ *     returns NULL.
+ *
+ *   Expects that xentoollog_logger_MINE is a struct whose
+ *   first member is
+ *            xentoollog_logger vtable;
+ *
+ *   Expects that
+ *      MINE_vmessage
+ *      MINE_progress
+ *      MINE_destroy
+ *   are in scope, with types compatible with the vtable members.
+ *
+ */
 #define XTL_NEW_LOGGER(LOGGER,buffer) ({                                \
     xentoollog_logger_##LOGGER *new_consumer;                           \
                                                                         \
-- 
1.7.10.4