docs: explain in greater details what the functions do
Warning, cannot access the index:
_darcs/index: opening of '_darcs/index' failed: permission denied (Permission denied)
diff -rN -u old-repo/docs/index.txt new-repo/docs/index.txt
--- old-repo/docs/index.txt 2022-09-28 12:09:07.196640382 +0200
+++ new-repo/docs/index.txt 2022-09-28 12:09:07.196640382 +0200
@@ -1,5 +1,5 @@
==========================================
-feller, EPICS support for logging to files
+Feller: EPICS support for logging to files
==========================================
.. image:: epics-logo.png
@@ -19,11 +19,10 @@
About
=====
-Feller is a simple support module for the *Experimental
-Physics and Industrial Control System* (`EPICS`_). It provides
-the possibility to log messages from any subsystem (a C file, a library,
-an SNL program, whatever) to a specified file. It uses the
-standard EPICS errlog facility in order not to disturb the normal
+Feller is a simple support module for the *Experimental Physics and Industrial
+Control System* (`EPICS`_). It provides the possibility to log messages from any
+subsystem (a C file, a library, an SNL program, whatever) to a specified file. It
+uses the standard EPICS errlog facility in order not to disturb the normal
processing, even if acessing the file is slow.
Download
@@ -72,34 +71,50 @@
::
struct feller *fellerCreate(const char *filename);
-
-Create a feller object. The argument is the name of the file you want your
-messages to be logged to.
+
+Create a feller object. The argument is the name of the file you want your messages
+to be logged to. The ``filename`` gets hashed and the hash is turned into a prefix
+string stored inside the feller. Any message that starts with this prefix string is
+considered to be intended for this feller. To prepend the prefix, use
+``fellerGetPrefix``, see below. This procedure also opens the file for appending.
+
+If the file cannot be opened, ``fellerCreate`` returns ``NULL`` and issues an error
+message.
+
+If there already exists a feller with the same ``filename``, ``fellerCreate`` will
+*not* create a new one; instead, it will return the existing feller and output a
+warning message (since often this will not be intended). Such fellers are referred
+to as "shared" in what follows.
::
fellerDestroy(struct feller *this)
-Destroy a feller object.
+Destroy a feller object. If the feller is not shared, the file gets closed, and the
+feller de-registers itself from the errlog system. If the feller is shared, then
+only an internal reference counter is decremented.
+
+This means in order to really destroy a feller and close the file, ``fellerDestroy``
+has to be called as often as ``fellerCreate`` (for the same ``filename``).
::
char *fellerGetPrefix(struct feller *this)
-Return a (hopefully) unique (but short) string identifying the messages
-for this feller. You need to prepend all the messages intended for your
-feller with this string. The prefix string itself will be removed from the
-message before it gets written to the file.
+Return a (hopefully) unique (but short) string identifying the messages for this
+feller. You need to prepend all the messages intended for your feller with this
+string. The prefix string itself will be removed from the message before it gets
+written to the file.
::
#define fellerPrintf(feller, format, args...)\
errlogPrintfNoConsole("%s" format, fellerGetPrefix(feller), ## args)
-To actually log a message, you can call any of the standard errlog functions.
-This macro is a convenience wrapper for the most common case when you do not
-want to print the message to the console. You can of course define your own
-wrapper macros, maybe calling other errlog print functions.
+To actually log a message, you can call any of the standard errlog functions. This
+macro is a convenience wrapper for the most common case when you do not want to
+print the message to the console. You can of course define your own wrapper macros,
+maybe calling other errlog print functions.
.. warning::
patch 3bf979888922ffe41874e8adf4d2883d127afc32
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 21:32:27 CEST 2013
* docs: explain in greater details what the functions d