docs: renamed Release Notes to Change Log, cleaned up its entries --> to head
Warning, cannot access the index:
_darcs/index: opening of '_darcs/index' failed: permission denied (Permission denied)
diff -rN -u old-repo/Makefile new-repo/Makefile
--- old-repo/Makefile 2022-11-28 23:38:44.440763470 +0100
+++ new-repo/Makefile 2022-11-28 23:38:44.440763470 +0100
@@ -9,7 +9,7 @@
src_DEPEND_DIRS = configure
testTop_DEPEND_DIRS = src
-FELLER_RELEASE = 0.3
+FELLER_RELEASE = 0.4
DEFAULT_REPO = /opt/repositories/controls/darcs/epics/support/feller
FELLER_PATH = www/control/SoftDist/feller
diff -rN -u old-repo/configure/CONFIG_SITE new-repo/configure/CONFIG_SITE
--- old-repo/configure/CONFIG_SITE 2022-11-28 23:38:44.440763470 +0100
+++ new-repo/configure/CONFIG_SITE 2022-11-28 23:38:44.440763470 +0100
@@ -31,8 +31,3 @@
# You must rebuild in the iocBoot directory for this to
# take effect.
#IOCS_APPL_TOP = </IOC/path/to/application/top>
-
-# You might want to remove the comment on the next line if you
-# use EPICS base version 3.14.12.3 or older, but have
-# applied add_errlogRemoveSingleListener.patch to it.
-#USR_CFLAGS += -DBASE_HAS_errlogRemoveSingleListener
diff -rN -u old-repo/docs/ChangeLog.txt new-repo/docs/ChangeLog.txt
--- old-repo/docs/ChangeLog.txt 1970-01-01 01:00:00.000000000 +0100
+++ new-repo/docs/ChangeLog.txt 2022-11-28 23:38:44.440763470 +0100
@@ -0,0 +1,43 @@
+==========
+Change Log
+==========
+
+.. _Release 0.4:
+
+Release 0.4
+===========
+
+* docs: applied the rest of J.L. Muir's typo fixes
+* removed the #ifdefs in the implementation (and their documentation)
+* added ref counts for shared fellers and fixed some bugs
+* docs: explain in greater details what the functions do
+
+.. _Release 0.3:
+
+Release 0.3
+===========
+
+* work around broken errlogRemoveListener
+* docs: add documentation for the work around, link to release notes
+* docs: added Change Log
+* docs: fixed some typos (thx to J. Lewis Muir" <jlmuir@imca-cat.org>)
+* test: give the errlog task a chance to do something
+* test: make the SNL program produce output faster
+* top/Makefile: restructured html generation rules
+
+.. _Release 0.2:
+
+Release 0.2
+===========
+
+* make upload target more robust
+* use a parameter to the SNL program,
+ start the SNL program and the other test in the startup file
+* removed generated log files from repo
+
+.. _Release 0.1:
+
+Release 0.1
+===========
+
+Initial release.
diff -rN -u old-repo/docs/ReleaseNotes.txt new-repo/docs/ReleaseNotes.txt
--- old-repo/docs/ReleaseNotes.txt 2022-11-28 23:38:44.440763470 +0100
+++ new-repo/docs/ReleaseNotes.txt 1970-01-01 01:00:00.000000000 +0100
@@ -1,35 +0,0 @@
-=============
-Release Notes
-=============
-
-.. _Release 0.3:
-
-Release 0.3
-===========
-
-* work around broken errlogRemoveListener
-* docs: add documentation for the work around, link to release notes
-* docs: added release notes
-* docs: fixed a copy/paste error
-* docs: fixed some typos (thx to J. Lewis Muir" <jlmuir@imca-cat.org>)
-* test: give the errlog task a chance to do something
-* test: make the SNL program produce output faster
-* top/Makefile: added docs to .PHONY targets
-* top/Makefile: restructured html generation rules
-
-.. _Release 0.2:
-
-Release 0.2
-===========
-
-* make upload target more robust
-* use a parameter to the SNL program,
- start the SNL program and the other test in the startup file
-* removed generated log files from repo
-
-.. _Release 0.1:
-
-Release 0.1
-===========
-
-Initial release.
diff -rN -u old-repo/docs/conf.py new-repo/docs/conf.py
--- old-repo/docs/conf.py 2022-11-28 23:38:44.440763470 +0100
+++ new-repo/docs/conf.py 2022-11-28 23:38:44.440763470 +0100
@@ -45,9 +45,9 @@
# built documents.
#
# The short X.Y version.
-version = '0.3'
+version = '0.4'
# The full version, including alpha/beta/rc tags.
-release = '0.3'
+release = '0.4'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff -rN -u old-repo/docs/index.txt new-repo/docs/index.txt
--- old-repo/docs/index.txt 2022-11-28 23:38:44.440763470 +0100
+++ new-repo/docs/index.txt 2022-11-28 23:38:44.444763568 +0100
@@ -1,5 +1,5 @@
==========================================
-feller, EPICS support for logging to files
+Feller: EPICS support for logging to files
==========================================
.. image:: epics-logo.png
@@ -7,24 +7,24 @@
:Maintainer: Ben Franksen <benjamin.franksen@helmholtz-berlin.de>
:Bug Reports: tech-talk@aps.anl.gov
+:Stability: experimental
.. toctree::
:hidden:
Home <self>
- ReleaseNotes
+ ChangeLog
Welcome to the home page of the **feller** project.
About
=====
-The *feller* is a very simple support module for the *Experimental
-Physics and Industrial Controls System*, short `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 facilicty in order not to disturb the normal
-processing, even if acessing the file is slow.
+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 accessing the file is slow.
Download
========
@@ -34,8 +34,9 @@
http://www-csr.bessy.de/control/SoftDist/feller/releases/
========= ===========================
- Version Release Notes
+ Version Change Log
--------- ---------------------------
+ `0.4`_ :ref:`Release 0.4`
`0.3`_ :ref:`Release 0.3`
`0.2`_ :ref:`Release 0.2`
`0.1`_ :ref:`Release 0.1`
@@ -49,6 +50,7 @@
`latest snapshot`_.
.. _latest snapshot: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-snapshot-latest.tar.gz
+.. _0.4: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.4.tar.gz
.. _0.3: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.3.tar.gz
.. _0.2: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.2.tar.gz
.. _0.1: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.1.tar.gz
@@ -58,25 +60,11 @@
Follow the usual procedure for installing an EPICS support module.
-EPICS base versions 3.14.12.3 and earlier do not have the function
-errlogRemoveSingleListener. If you use such a base version you have two
-possibilities:
-
-1. You can apply ``add_errlogRemoveSingleListener.patch`` to your base
- and (in feller) uncomment the definition of BASE_HAS_errlogRemoveSingleListener
- in ``configure/CONFIG_SITE``.
-
-2. You just compile/install feller as is and leave
- BASE_HAS_errlogRemoveSingleListener undefined. This will cause an
- implementation to be compiled that works around the missing function
- by adding only one errlog listener (and never removing it), and which
- traverses the internal list of fellers itself (rather than letting the
- errlog facility do it).
-
API
===
-There is one type and 3 functions, and a (convenience) macro.
+There is one type and 3 functions, and a (convenience) macro. To use them, include
+"feller.h".
::
@@ -87,34 +75,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 *fellerGetHeader(struct feller *this)
+ 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 header 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, fellerGetHeader(feller), ## 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::
diff -rN -u old-repo/src/feller.c new-repo/src/feller.c
--- old-repo/src/feller.c 2022-11-28 23:38:44.440763470 +0100
+++ new-repo/src/feller.c 2022-11-28 23:38:44.444763568 +0100
@@ -7,24 +7,16 @@
#include "epicsString.h"
#include "epicsMutex.h"
#include "epicsThread.h"
-#include "epicsVersion.h"
#include "feller.h"
-#define EPICS_COMPLETE_VERSION\
- (EPICS_PATCH_LEVEL + 100*(EPICS_MODIFICATION + 100*(EPICS_REVISION + 100*EPICS_VERSION)))
-
-#ifndef BASE_HAS_errlogRemoveSingleListener
-#define BASE_HAS_errlogRemoveSingleListener (EPICS_COMPLETE_VERSION > 3141203)
-#endif
-
-
#define PREFIX_LENGTH (2 + 2 * sizeof(unsigned int))
struct feller {
FILE *file;
char prefix[PREFIX_LENGTH+1];
unsigned int hash;
+ unsigned refcount;
struct feller *next;
};
@@ -36,7 +28,6 @@
static void fellerListener(void *pvt, const char *message)
{
-#if !BASE_HAS_errlogRemoveSingleListener
struct feller *this;
epicsMutexLockStatus r;
r = epicsMutexLock(mutex);
@@ -46,17 +37,13 @@
}
this = firstFeller; /* ignore pvt */
while (this) {
-#else
- struct feller *this = (struct feller *)pvt;
-#endif
if (strncmp(message, this->prefix, 10)==0) {
+ assert(this->file);
fputs(message + PREFIX_LENGTH, this->file);
}
-#if !BASE_HAS_errlogRemoveSingleListener
this = this->next;
}
epicsMutexUnlock(mutex);
-#endif
}
static void fellerInitOnce(void *parm)
@@ -64,9 +51,7 @@
mutex = epicsMutexMustCreate();
seed = epicsStrHash("feller", 0x2099);
firstFeller = NULL;
-#if !BASE_HAS_errlogRemoveSingleListener
errlogAddListener(fellerListener, NULL);
-#endif
}
epicsShareFunc struct feller *fellerCreate(const char *filename)
@@ -88,24 +73,29 @@
this = this->next;
}
if (!this) {
+ FILE *file = fopen(filename, "a");
+ if (!file) {
+ errlogPrintf("fellerCreate: error cannot open file '%s'"
+ " for appending\n", filename);
+ epicsMutexUnlock(mutex);
+ return NULL;
+ }
this = calloc(1,sizeof(struct feller));
if (!this) {
errlogPrintf("fellerCreate: out of memory\n");
epicsMutexUnlock(mutex);
return NULL;
}
+ this->file = file;
this->next = firstFeller;
firstFeller = this;
this->hash = hash;
+ epicsSnprintf(this->prefix, PREFIX_LENGTH+1, "[%08x]", hash);
} else {
errlogPrintf("fellerCreate: warning re-using already existing instance"
" for file '%s'\n", filename);
}
- epicsSnprintf(this->prefix, PREFIX_LENGTH+1, "[%08x]", hash);
- this->file = fopen(filename, "a");
-#if BASE_HAS_errlogRemoveSingleListener
- errlogAddListener(fellerListener, this);
-#endif
+ this->refcount++;
epicsMutexUnlock(mutex);
return this;
}
@@ -114,32 +104,33 @@
{
epicsMutexLockStatus r;
-#if BASE_HAS_errlogRemoveSingleListener
- errlogFlush();
- errlogRemoveSingleListener(fellerListener, this);
-#endif
-
r = epicsMutexLock(mutex);
if (r != epicsMutexLockOK) {
errlogPrintf("fellerDestroy: mutex unavailable\n");
return;
}
- if (firstFeller == this) {
- firstFeller = this->next;
- } else {
- struct feller *other = firstFeller;
- while (other) {
- if (other->next == this) {
- other->next = this->next;
- break;
- } else {
- other = other->next;
+ if (--this->refcount == 0) {
+ if (firstFeller == this) {
+ firstFeller = this->next;
+ } else {
+ struct feller *other = firstFeller;
+ while (other) {
+ if (other->next == this) {
+ other->next = this->next;
+ break;
+ } else {
+ other = other->next;
+ }
}
}
+ assert(this->file);
+ fflush(this->file);
+ fclose(this->file);
+ free(this);
+ } else {
+ errlogPrintf("fellerDestroy: warning not yet destroying"
+ " shared feller instance\n");
}
- fflush(this->file);
- fclose(this->file);
- free(this);
epicsMutexUnlock(mutex);
}
patch 987b0b8d38b2032fd40c120e27b0bf69d0675f18
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 23:03:45 CEST 2013
* fixed a typo in the docs
patch 6f74d13750a0bed10efd5bab0e24ec0a2f90ec3f
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 21:41:39 CEST 2013
tagged R0-4
patch a850e5cf8ace4af96a81ae08ea43e6bdd5599814
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 21:40:29 CEST 2013
* bump release to 0.4, updated change log
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 do
patch 897d5cc5829ddd612b78d975377a3cbdbc407800
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 21:27:36 CEST 2013
* added ref counts for shared fellers and fixed some bugs
patch eb112ba37bc77f10c8d99650530a4f335e7c08da
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 21:24:39 CEST 2013
* removed the #ifdefs in the implementation (and their documentation)
patch 16c0cc6aded5a35b5f713b04737b3ed4ff7bcf29
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 20:26:14 CEST 2013
* docs: applied the rest of J.L. Muir's typo fixes
patch 189c3e8bd22854d2b39f4d2bfda4070d24d60f98
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 15:16:47 CEST 2013
* docs: reflect renaming header -> prefix
patch 3d3664f47082d4a4cf3f7d3f8e6a79368df0fff9
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 14:58:13 CEST 2013
tagged R0-3
patch 1457dcbc4184479fc3e7023d8756c1ae96ab83bb
Author: benjamin.franksen@helmholtz-berlin.de
Date: Fri Jun 21 14:56:58 CEST 2013
* docs: renamed Release Notes to Change Log, cleaned up its entrie