This chapter and the next describe the facilities provided in <base>/src/libCom.
This chapter describes facilities which are platform independent.
The next chapter describes facilities which have different implementations on different platforms.
bucketLib.h describes a hash facility for integers, pointers, and strings.
It is used by the Channel Access Server.
It is currently undocumented.
postfix.h defines several macros and the routines used by the calculation record type calcRecord, access security, and other code, to compile and evaluate mathematical expressions.
The syntax of the infix expressions accepted is described below.
long postfix(const char *psrc, char *ppostfix, short *perror); long calcArgUsage(const char *ppostfix, unsigned long *pinputs, unsigned long *pstores); const char * calcErrorStr(short error); long calcPerform(double *parg, double *presult, const char *ppostfix);
The postfix() routine converts an expression from infix to postfix notation.
It is the callers's responsibility to ensure that ppostfix points to sufficient storage to hold the postfix expression.
The macro INFIX_TO_POSTFIX_SIZE(n) can be used to calculate an appropriate postfix buffer size from the length of the infix buffer (note that n must count the terminating nil byte too).
There is no maximum length to the input expression that can be accepted, although there are internal limits to the complexity of the expressions that can be converted and evaluated. If postfix() returns a non-zero value it will have placed an error code at the location pointed to by perror.
The error codes used are defined in postfix.h as a series of macros with names starting CALC_ERR_, but a string representation of the error code is more useful and can be obtained by passing the value to the calcErrorStr() routine, which returns a static error message string explaining the error.
Software using the calc subsystem may need to know what expression arguments are used and/or modified by a particular expression. It can discover this from the postfix string by calling calcArgUsage(), which takes two pointers pinputs and pstores to a pair of unsigned long bitmaps which return that information to the caller. Passing a NULL value for either of these pointers is legal if only the other is needed.
The least signficant bit (bit 0) of the bitmap at *pinputs will be set if the expression depends on the argument A, and so on through bit 11 for the argument L. Similarly, bit 0 of the bitmap at *pstores will be set if the expression assigns a value to the argument A. An argument that is not used until after a value has been assigned to it will not be set in the pinputs bitmap, thus the bits can be used to determine whether a value needs to be supplied for their associated argument or not for the purposes of evaluating the expression. The return value from calcArgUsage() will be non-zero if the ppostfix expression was illegal, otherwise 0.
The postfix expression is evaluated by calling the calcPerform() routine, which returns the status values 0 for OK, or non-zero if an error is discovered during the evaluation process.
The arguments to calcPerform() are:
The infix expressions that can be used are very similar to the C expression syntax, but with some additions and subtle differences in operator meaning and precedence.
The string may contain a series of expressions separated by a semi-colon character `;' any one of which may actually provide the calculation result;
however all of the other expressions included must assign their result to a variable.
All alphabetic elements described below are case independent, so upper and lower case letters may be used and mixed in the variable and function names as desired.
Spaces may be used anywhere within an expression except between the characters that make up a single expression element.
The simplest expression element is a numeric literal, any (positive) number expressed using the standard floating point syntax that can be stored as a double precision value.
This now includes the values Infinity and NaN (not a number).
Note that negative numbers will be encoded as a positive literal to which the unary negate operator is applied.
Examples:
1 2.718281828459 Inf
There are three trigonometric constants available to any expression which return a value:
pi returns the value of the mathematical constant 
.
D2R evaluates to /180 which, when used as a multiplier, converts an angle from degrees to radians.
R2D evaluates to 180/ which as a multiplier converts an angle from radians to degrees.
Variables are used to provide inputs to an expression, and are named using the single letters A through L inclusive or the keyword VAL which refers to the previous result of this calculation.
The software that makes use of the expression evaluation code should document how the individual variables are given values;
for the calc record type the input links INPA through INPL can be used to obtain these from other record fields, and VAL refers to the the VAL field (which can be overwritten from outside the record via Channel Access or a database link).
Recently added is the ability to assign the result of a sub-expression to any of the single letter variables, which can then be used in another sub-expression.
The variable assignment operator is the character pair := and must immediately follow
the name of the variable to receive the expression value.
Since the infix string must return exactly one value, every expression string must have exactly one sub-expression that is not an assignment, which can appear anywhere in the string.
Sub-expressions within the string are separated by a semi-colon character.
Examples:
B; B:=A i:=i+1; a*sin(i*D2R)
The usual binary arithmetic operators are provided:
+ - * and / with their usual relative precedence and left-to-right associativity, and - may also be used as a unary negate operator where it has a higher precedence and associates from right to left.
There is no unary plus operator, so numeric literals cannot begin with a + sign.
Examples:
a*b + c a/-4 - b
Three other binary operators are also provided:
% is the integer modulo operator, while the synonymous operators ** and ^ raise their left operand to the power of the right operand.
% has the same precedence and associativity as * and /, while the power operators associate left-to-right and have a precedence in between * and unary minus.
Examples:
e:=a%10; d:=a/10%10; c:=a/100%10; b:=a/1000%10; b*4096+c*256+d*16+e sqrt(a**2 + b**2)
Various algebraic functions are available which take parameters inside parentheses. The parameter seperator is a comma.
abs(a)
exp(a)
log(a)
ln(a) or loge(a)
max(a, b, ...)
min(a, b, ...)
sqr(a) or sqrt(a)
Standard circular trigonometric functions, with angles expressed in radians:
sin(a)
cos(a)
tan(a)
asin(a)
acos(a)
atan(a)
atan2(a, b) - Note that these arguments are the reverse of the ANSI C function, so while C would return arctan(a/b) the calc expression engine returns arctan(b/a)
The basic hyperbolic functions are provided, but no inverse functions (which are not provided by the ANSI C math library either).
sinh(a)
cosh(a)
tanh(a)
The numeric functions perform operations related to the floating point numeric representation and truncation or rounding.
ceil(a)
floor(a)
nint(a)
isinf(a)
isnan(a, ...)
finite(a, ...)
rndm
These operators regard their arguments as true or false, where 0.0 is false and any other value is true.
a && b
a || b
!a
The bitwise operators convert their arguments to an integer (by truncation), perform the appropriate bitwise operation and convert back to a floating point value.
Unlike in C though, ^ is not a bitwise exclusive-or operator.
a & b or a and b
a | b or a or b
a xor b
~a or not a
a << b
a >> b
Standard numeric comparisons between two values:
a < b
a <= b
a = b or a == b
a >= b
a > b
a != b or a # b
Expressions can use the C conditional operator, which has a lower precedence than all of the other operators except for the assignment operator.
? true result : false result
Example:
a < 360 ? a+1 : 0
Sub-expressions can be placed within parentheses to override operator precence rules. Parentheses can be nested to any depth, but the intermediate value stack used by the expression evaluation engine is limited to 80 results (which requirea an expression at least 321 characters long to reach).
This subdirectory of libCom is intended for facilities such as class and function templates that implement parts of the ISO standard C++ library where such facilities are not available or not efficient on all the target platforms on which EPICS is supported. EPICS does not make use of the C++ container templates because the large number of memory allocation and deletion operations that these use causes memory pool fragmentation on some platforms, threatening the lifetime of an individual IOC.
epicsAlgorithm.h contains a few templates that are also available in the C++ standard header algorithm, but are provided here in a much smaller file.
algorithm contains many templates for sorting and searching through C++ template containers which are not used in EPICS.
If all you need from there is std::min(), std::max() and/or std::swap() your code may compile faster if you include epicsAlgorithm.h and use epicsMin(), epicsMax() and epicsSwap() instead.
| template <class T> | Meaning |
|---|---|
| const T& epicsMin(const T& a, const T& b) | Returns the smaller of a or b compared using a<b. Handles NaNs correctly. |
| const T& epicsMax(const T& a, const T& b) | Returns the larger of a or b compared using a<b. Handles NaNa correctly. |
| void epicsSwap(T& a, T& b) | Swaps the values of a and b; T must have a copy-constructor and operator=. |
void epicsExit(int status); void epicsExitCallAtExits(void); void epicsAtExit(void (*epicsExitFunc)(void *arg), void *arg); void epicsExitCallAtThreadExits(void); int epicsAtThreadExit(void (*epicsExitFunc)(void *arg), void *arg);
This is an extended replacement for the Posix exit and atexit routines, which also provides a pointer argument to pass to the exit handlers.
This facility was created because of problems on vxWorks and windows with the implementation of atexit, i.e. neither of these systems implement exit and atexit according to the POSIX standard.
| Method | Meaning |
|---|---|
| epicsExit | This calls epicsExitCallAtExits and then passes status on to exit. |
| epicsExitCallAtExits | This calls each of the functions registered by prior calls to epicsAtExit, in reverse order of their registration. Most applications will not call this routine directly. |
| epicsAtExit | Register a function and an associated context parameter, to be called with the given parameter when epicsExitCallAtExits is invoked. |
| epicsExitCallAtThreadExits | This calls each of the functions that were registered by the current thread calling epicsAtThreadExit, in reverse order of the function registration. This routine is called automatically when an epicsThread's main entry method returns, but will not be run if the thread is stopped by other means. |
| epicsAtThreadExit | Register a function and an associated context parameter. The function will be called with the given parameter when epicsExitCallAtThreadExits is invoked by the current thread ending normally, i.e. when the thread function returns. |
cvtFast.h provides routines for converting various numeric types into an ascii string.
They offer a combination of speed and convenience not available with sprintf().
/* These functions return the number of ASCII characters generated */
int cvtFloatToString(float value, char *pstr, unsigned short precision);
int cvtDoubleToString(double value, char *pstr, unsigned short prec);
int cvtFloatToExpString(float value, char *pstr, unsigned short prec);
int cvtDoubleToExpString(double value, char *pstr, unsigned short prec);
int cvtFloatToCompactString(float value, char *pstr, unsigned short prec);
int cvtDoubleToCompactString(double value, char *pstr, unsigned short prec);
int cvtCharToString(char value, char *pstring);
int cvtUcharToString(unsigned char value, char *pstr);
int cvtShortToString(short value, char *pstr);
int cvtUshortToString(unsigned short value, char *pstr);
int cvtLongToString(epicsInt32 value, char *pstr);
int cvtUlongToString(epicsUInt32 value, char *pstr);
int cvtLongToHexString(epicsInt32 value, char *pstr);
int cvtLongToOctalString(epicsInt32 value, char *pstr);
unsigned long cvtBitsToUlong(
epicsUInt32 src,
unsigned bitFieldOffset,
unsigned bitFieldLength);
unsigned long cvtUlongToBits(
epicsUInt32 src,
epicsUInt32 dest,
unsigned bitFieldOffset,
unsigned bitFieldLength);
This directory contains the following C++ template headers:
resourceLib.h - A C++ hash facility that implements the same functionality as bucketLib
tsBTree.h - Binary tree.
tsDLList.h - Double Linked List
tsFreeList.h - Free List for efficient new/delete
tsMinMax.h - min and max.
tsSLList.h - Single Linked List
Currently these are only being used by Channel Access Clients and the portable Channel Access Server. It has not been decided if any of these will remain in libCom.
dbmf.h (Database Macro/Free) describes a facility that prevents memory fragmentation when memory is allocated and then freed a short time later.
Routines within iocCore like dbLoadDatabase() have the following attributes:
In some environments, e.g. vxWorks 5.x, this behavior causes severe memory fragmentation.
The dbmf facility stops the memory fragmentation. It should NOT be used by code that allocates storage and then keeps it for a considerable period of time before releasing. Such code can use the freeList library described below.
int dbmfInit(size_t size, int chunkItems); void *dbmfMalloc(size_t bytes); void dbmfFree(void* bytes); void dbmfFreeChunks(void); int dbmfShow(int level);
| Routine | Meaning |
|---|---|
| dbmfInit() | Initialize the facility. Each time malloc() must be called size*chunkItems bytes are allocated. size is the maximum size request from dbmfMalloc() that will be allocated from the dbmf pool. If dbmfInit() was not called before one of the other routines then it is automatically called with size=64 and chuckItems=10. |
| dbmfMalloc() | Allocate memory. If bytes is > size then malloc() is used to allocate the memory. |
| dbmfFree() | Free the memory allocated by dbmfMalloc(). |
| dbmfFreeChunks() | Free all chunks that have contain only free items. |
| dbmfShow() | Show the status of the dbmf memory pool. |
ellLib.h describes a double linked list library. It provides functionality similar to the vxWorks lstLib library. See the
vxWorks documentation for details. There is an ellXXX() routine to replace most vxWorks lstXXX() routines.
typedef struct ELLNODE {
struct ELLNODE *next;
struct ELLNODE *previous;
}ELLNODE;
typedef void (*FREEFUNC)(void *);
typedef struct ELLLIST {
ELLNODE node;
int count;
void ellInit (ELLLIST *pList);
int ellCount (ELLLIST *pList);
ELLNODE *ellFirst (ELLLIST *pList);
ELLNODE *ellLast (ELLLIST *pList);
ELLNODE *ellNext (ELLNODE *pNode);
ELLNODE *ellPrevious (ELLNODE *pNode);
void ellAdd (ELLLIST *pList, ELLNODE *pNode);
void ellConcat (ELLLIST *pDstList, ELLLIST *pAddList);
void ellDelete (ELLLIST *pList, ELLNODE *pNode);
void ellExtract (ELLLIST *pSrcList, ELLNODE *pStartNode,
ELLNODE *pEndNode, ELLLIST *pDstList);
ELLNODE *ellGet (ELLLIST *pList);
void ellInsert (ELLLIST *plist, ELLNODE *pPrev, ELLNODE *pNode);
ELLNODE *ellNth (ELLLIST *pList, int nodeNum);
ELLNODE *ellNStep (ELLNODE *pNode, int nStep);
int ellFind (ELLLIST *pList, ELLNODE *pNode);
void ellFree2 (ELLLIST *pList, FREEFUNC freeFunc);
void ellFree (ELLLIST *pList); // Use only if freeFunc is free()
void ellVerify (ELLLIST *pList);
epicsRingBytes.h contains
epicsRingBytesId epicsRingBytesCreate(int nbytes); void epicsRingBytesDelete(epicsRingBytesId id); int epicsRingBytesGet(epicsRingBytesId id, char *value,int nbytes); int epicsRingBytesPut(epicsRingBytesId id, char *value,int nbytes); void epicsRingBytesFlush(epicsRingBytesId id); int epicsRingBytesFreeBytes(epicsRingBytesId id); int epicsRingBytesUsedBytes(epicsRingBytesId id); int epicsRingBytesSize(epicsRingBytesId id); int epicsRingBytesIsEmpty(epicsRingBytesId id); int epicsRingBytesIsFull(epicsRingBytesId id);
| Method | Meaning |
|---|---|
| epicsRingBytesCreate() | Create a new ring buffer of size nbytes. The returned epicsRingBytesId is passed to the other ring methods. |
| epicsRingBytesDelete() | Delete the ring buffer and free any associated memory. |
| epicsRingBytesGet() | Move up to nbytes from the ring buffer to value. The number of bytes actually moved is returned. |
| epicsRingBytesPut() | Move nbytes from value to the ring buffer if there is enough free space available to hold them. The number of bytes actually moved is returned, which will be zero if insufficient space exists. |
| epicsRingBytesFlush() | Make the ring buffer empty. |
| epicsRingBytesFreeBytes() | Return the number of free bytes in the ring buffer. |
| epicsRingBytesUsedBytes() | Return the number of bytes currently stored in the ring buffer. |
| epicsRingBytesSize() | Return the size of the ring buffer, i.e., nbytes specified in the call to epicsRingBytesCreate(). |
| epicsRingBytesIsEmpty() | Return (true, false) if the ring buffer is currently empty. |
| epicsRingBytesIsFull() | Return (true, false) if the ring buffer is currently empty. |
epicsRingBytes has the following properties:
epicsRingPointer.h describes a C++ and a C facility for a commonly used type of ring buffer.
EpicsRingPointer provides methods for creating and using ring buffers (first in first out circular buffers) that store pointers. It is designed so that a writer thread and reader thread can access the ring simultaneously without requiring mutual exclusion.
template <class T>
class epicsRingPointer {
public:
epicsRingPointer(int size);
~epicsRingPointer();
bool push(T *p);
T* pop();
void flush();
int getFree() const;
int getUsed() const;
int getSize() const;
bool isEmpty() const;
bool isFull() const;
private: // Prevent compiler-generated member functions
// default constructor, copy constructor, assignment operator
epicsRingPointer();
epicsRingPointer(const epicsRingPointer &);
epicsRingPointer& operator=(const epicsRingPointer &);
private: // Data
...
};
An epicsRingPointer cannot be assigned to, copy-constructed, or constructed without giving the size argument. The C++ compiler will object to some of the statements below:
epicsRingPointer rp0(); // Error: default constructor is private epicsRingPointer rp1(10); // OK epicsRingPointer rp2(t1); // Error: copy constructor is private epicsRingPointer *prp; // OK, pointer *prp = rp1; // Error: assignment operator is private prp = &rp1; // OK, pointer assignment and address-of
| Method | Meaning |
|---|---|
| epicsRingPointer() | Constructor. The size is the maximum number of elements (pointers) that can be stored in the ring. |
| ~epicsRingPointer() | Destructor. |
| push() | Push a new entry on the ring. It returns (false,true) is (failure, success). Failure means the ring was full. If a single writer is present it does not have to use a lock while performing the push. If multiple writers are present they must use a common lock while issuing the push. |
| pop() | Take a element off the ring. It returns 0 (null) if the ring was empty. If a single reader is present it does not have to lock while issuing the pop. If multiple readers are present they must use a common lock while issuing the pop. |
| flush() | Remove all elements from the ring. If this operation is performed then all access to the ring should be locked. |
| getFree() | Return the amount of empty space in the ring, i.e. how many additional elements it can hold. |
| getUsed() | Return the number of elements stored on the ring |
| getSize() | Return the size of the ring, i.e. the value of size specified when the ring was created. |
| isEmpty() | Returns true if the ring is empty, else false. |
| isFull() | Returns true if the ring is full, else false. |
typedef void *epicsRingPointerId;
epicsRingPointerId epicsRingPointerCreate(int size);
void epicsRingPointerDelete(epicsRingPointerId id);
/*epicsRingPointerPop returns 0 if the ring was empty */
void * epicsRingPointerPop(epicsRingPointerId id) ;
/*epicsRingPointerPush returns (0,1) if p (was not, was) put on ring*/
int epicsRingPointerPush(epicsRingPointerId id,void *p);
void epicsRingPointerFlush(epicsRingPointerId id);
int epicsRingPointerGetFree(epicsRingPointerId id);
int epicsRingPointerGetUsed(epicsRingPointerId id);
int epicsRingPointerGetSize(epicsRingPointerId id);
int epicsRingPointerIsEmpty(epicsRingPointerId id);
int epicsRingPointerIsFull(epicsRingPointerId id);
Each C function corresponds to one of the C++ methods.
epicsTimer.h describes a C++ and a C timer facility.
class epicsTimerNotify {
public:
enum restart_t { noRestart, restart };
class expireStatus {
public:
expireStatus ( restart_t );
expireStatus ( restart_t, const double &expireDelaySec );
bool restart () const;
double expirationDelay () const;
private:
double delay;
};
virtual ~epicsTimerNotify ();
// return noRestart OR return expireStatus ( restart, 30.0 /* sec */ );
virtual expireStatus expire ( const epicsTime & currentTime ) = 0;
virtual void show ( unsigned int level ) const;
};
class epicsTimer {
public:
virtual void destroy () = 0; // requires existence of timer queue
virtual void start ( epicsTimerNotify &, const epicsTime & ) = 0;
virtual void start ( epicsTimerNotify &, double delaySeconds ) = 0;
virtual void cancel () = 0;
struct expireInfo {
expireInfo ( bool active, const epicsTime & expireTime );
bool active;
epicsTime expireTime;
};
virtual expireInfo getExpireInfo () const = 0;
double getExpireDelay ();
virtual void show ( unsigned int level ) const = 0;
protected:
virtual ~epicsTimer () = 0; // use destroy
};
| Method | Meaning |
|---|---|
| epicsTimerNotifyexpire() | Code using an epicsTimer must include a class that inherits from epicsTimerNotify. The derived class must implement the method expire(), which is called by the epicsTimer when the associated timer expires. epicsTimerNotify defines a class expireStatus which makes it easy to implement both one shot and periodic timers. A one-shot expire() returns with the statement: return(noRestart);A periodic timer returns with a statement like: return(restart,10.0);where is second argument is the delay until the next callback. |
| epicsTimer | epicsTimer is an abstract base class. An epics timer can only be created by calling createTimer, which is a method of epicsTimerQueue. |
| destroy | This is provided instead of a destructor. This will automatically call cancel before freeing all resources used by the timer. |
| start() | Starts the timer to expire either at the specified time or the specified number of seconds in the future. If the timer is already active when start is called, it is first canceled. |
| cancel() | If the timer is scheduled, cancel it. If it is not scheduled do nothing. Note that if the expire() method is already running, this call delays until the expire() completes. |
| getExpireInfo | Get expireInfo, which says if timer is active and if so when it expires. |
| getExpireDelay() | Return the number of seconds until the timer will expire. If the timer is not active it returns DBL_MAX |
| show() | Display info about object. |
class epicsTimerQueue {
public:
virtual epicsTimer & createTimer () = 0;
virtual void show ( unsigned int level ) const = 0;
protected:
virtual ~epicsTimerQueue () = 0;
};
| Method | Meaning |
|---|---|
| createTimer() | This is a ``factory" method to create timers which use this queue. |
| show() | Display info about object |
class epicsTimerQueueActive : public epicsTimerQueue {
public:
static epicsTimerQueueActive & allocate (
bool okToShare, unsigned threadPriority = epicsThreadPriorityMin + 10 );
virtual void release () = 0;
protected:
virtual ~epicsTimerQueueActive () = 0;
};
| Method | Meaning |
|---|---|
| allocate() | This is a ``factory" method to create a timer queue. If okToShare is (true,false) then a (shared, separate) thread will manage the timer requests.If the okToShare constructor parameter is true then if a timer queue is already running at the specified priority then it will be referenced for shared use by the application, and an independent timer queue will not be created.This method should not be called from within a C++ static constructor, since the queue thread requires that a current time provider be available and the last-resort time provider is not guaranteed to have been registered until all constructors have run.Editorial note: It is useful for two independent timer queues to run at the same priority if there are multiple processors, or if there is an application with well behaved timer expire functions that needs to be independent of applications with computationally intensive, mutex locking, or IO blocking timer expire functions. |
| release() | Release the queue, i.e. the calling facility will no longer use the queue. The caller MUST ensure that it does not own any active timers. When the last facility using the queue calls release, all resources used by the queue are freed. |
These two classes manage a timer queue for single threaded applications. Since it is single threaded, the application is responsible for requesting that the queue be processed.
class epicsTimerQueueNotify {
public:
// called when a new timer is inserted into the queue and the
// delay to the next expire has changed
virtual void reschedule () = 0;
// if there is a quantum in the scheduling of timer intervals
// return this quantum in seconds. If unknown then return zero.
virtual double quantum () = 0;
protected:
virtual ~epicsTimerQueueNotify () = 0;
};
class epicsTimerQueuePassive {
public:
static epicsTimerQueuePassive & create ( epicsTimerQueueNotify & );
virtual ~epicsTimerQueuePassive () = 0;
// process returns the delay to the next expire
virtual double process (const epicsTime & currentTime) = 0;
};
| Method | Meaning |
|---|---|
| epicsTimerQueueNotifyreschedule() | The virtual function epicsTimerQueueNotify::reschedule() is called when the delay to the next timer to expire on the timer queue changes. |
| epicsTimerQueueNotifyquantum | The virtual function epicsTimerQueueNotify::quantum() returns the timer expire interval scheduling quantum in seconds. This allows different types of timer queues to use application specific timer expire delay scheduling policies. The implementation of epicsTimerQueueActive employs epicsThreadSleep() for this purpose, and therefore epicsTimerQueueActive::quantum() returns the returned value from epicsThreadSleepQuantum(). Other types of timer queues might choose to schedule timer expiration using specialized hardware interrupts. In this case epicsTimerQueueNotify::quantum() might return a value reflecting the precision of a hardware timer. If unknown, then epicsTimerQueueNotify::quantum() should return zero. |
| epicsTimerQueuePassive | epicsTimerQueuePassive is an abstract base class so cannot be instantiated directly, but contains a static member function to create a concrete passive timer queue object of a (hidden) derived class. |
| create() | A ``factory" method to create a non-threaded timer queue. The calling software also passes an object derived from epicsTimerQueueNotify to receive reschedule() callbacks. |
| ~epicsTimerQueuePassive() | Destructor. The caller MUST ensure that it does not own any active timers, i.e. it must cancel any active timers before deleting the epicsTimerQueuePassive object. |
| process() | This calls expire() for all timers that have expired. The facility that creates the queue MUST call this. It returns the delay until the next timer will expire. |
typedef struct epicsTimerForC * epicsTimerId;
typedef void ( *epicsTimerCallback ) ( void *pPrivate );
/* thread managed timer queue */
typedef struct epicsTimerQueueActiveForC * epicsTimerQueueId;
epicsTimerQueueId epicsTimerQueueAllocate(
int okToShare, unsigned int threadPriority );
void epicsTimerQueueRelease ( epicsTimerQueueId );
epicsTimerId epicsTimerQueueCreateTimer ( epicsTimerQueueId queueid,
epicsTimerCallback callback, void *arg );
void epicsTimerQueueDestroyTimer ( epicsTimerQueueId queueid, epicsTimerId id );
void epicsTimerQueueShow ( epicsTimerQueueId id, unsigned int level );
/* passive timer queue */
typedef struct epicsTimerQueuePassiveForC * epicsTimerQueuePassiveId;
typedef void ( *epicsTimerQueueNotifyReschedule ) ( void *pPrivate );
typedef double ( * epicsTimerQueueNotifyQuantum ) ( void * pPrivate );
epicsTimerQueuePassiveId epicsTimerQueuePassiveCreate(
epicsTimerQueueNotifyReschedule,epicsTimerQueueNotifyQuantum,
void *pPrivate );
void epicsTimerQueuePassiveDestroy ( epicsTimerQueuePassiveId );
epicsTimerId epicsTimerQueuePassiveCreateTimer (epicsTimerQueuePassiveId queueid,
epicsTimerCallback pCallback, void *pArg );
void epicsTimerQueuePassiveDestroyTimer (
epicsTimerQueuePassiveId queueid,epicsTimerId id );
double epicsTimerQueuePassiveProcess ( epicsTimerQueuePassiveId );
void epicsTimerQueuePassiveShow(epicsTimerQueuePassiveId id,unsigned int level);
/* timer */
void epicsTimerStartTime(epicsTimerId id, const epicsTimeStamp *pTime);
void epicsTimerStartDelay(epicsTimerId id, double delaySeconds);
void epicsTimerCancel ( epicsTimerId id );
double epicsTimerGetExpireDelay ( epicsTimerId id );
void epicsTimerShow ( epicsTimerId id, unsigned int level );
The C interface provides most of the facilities as the C++ interface. It does not support the periodic timer features. The typedefs epicsTimerQueueNotifyReschedule and epicsTimerQueueNotifyQuantum are the ``C" interface equivalents to epicsTimerQueueNotify:: reschedule() and epicsTimerQueueNotify::quantum().
This example allocates a timer queue and two objects which have a timer that uses the queue. Each object is requested to schedule itself. The expire() callback just prints the name of the object. After scheduling each object the main thread just sleeps long enough for each expire to occur and then just returns after releasing the queue.
#include <stdio.h>
#include "epicsTimer.h"
class something : public epicsTimerNotify {
public:
something(const char* nm,epicsTimerQueueActive &queue)
: name(nm), timer(queue.createTimer()) {}
virtual ~something() { timer.destroy();}
void start(double delay) {timer.start(*this,delay);}
virtual expireStatus expire(const epicsTime & currentTime) {
printf("%s\n",name);
currentTime.show(1);
return(noRestart);
}
private:
const char* name;
epicsTimer &timer;
};
void epicsTimerExample()
{
epicsTimerQueueActive &queue = epicsTimerQueueActive::allocate(true);
{
something first("first",queue);
something second("second",queue);
first.start(1.0);
second.start(1.5);
epicsThreadSleep(2.0);
}
queue.release();
}
This example shows how C programs can use EPICS timers.
#include <stdio.h>
#include <epicsTimer.h>
#include <epicsThread.h>
static void
handler (void *arg)
{
printf ("%s timer tripped.\n", (char *)arg);
}
int
main(int argc, char **argv)
{
epicsTimerQueueId timerQueue;
epicsTimerId first, second;
/*
* Create the queue of timer requests
*/
timerQueue = epicsTimerQueueAllocate(1,epicsThreadPriorityScanHigh);
/*
* Create the timers
*/
first = epicsTimerQueueCreateTimer(timerQueue, handler, "First");
second = epicsTimerQueueCreateTimer(timerQueue, handler, "Second");
/*
* Start a timer
*/
printf("First timer should trip in 3 seconds.\n");
epicsTimerStartDelay(first, 3.0);
epicsThreadSleep(5.0);
printf("First timer should have tripped by now.\n");
/*
* Try starting and then cancelling a request
*/
printf("Second timer should trip in 3 seconds.\n");
epicsTimerStartDelay(first, 3.0);
epicsTimerStartDelay(second, 3.0);
epicsThreadSleep(1.0);
epicsTimerCancel(first);
epicsThreadSleep(5.0);
printf("Second timer should have tripped, first timer should not have
tripped.\n");
/*
* Clean up a single timer
*/
epicsTimerQueueDestroyTimer(timerQueue, first);
/*
* Clean up an entire queue of timers
*/
epicsTimerQueueRelease(timerQueue);
return 0;
File Descriptor Manager. fdManager.h describes a C++ implementation. fdmgr.h describes a C implementation.
Neither is currently documented.
freeList.h describes routines to allocate and free fixed size memory elements. Free elements are maintained on a
free list rather then being returned to the heap via calls to free. When it is necessary to call malloc(), memory is allocated
in multiples of the element size.
void freeListInitPvt(void **ppvt, int size, int nmalloc); void *freeListCalloc(void *pvt); void *freeListMalloc(void *pvt); void freeListFree(void *pvt, void*pmem); void freeListCleanup(void *pvt); size_t freeListItemsAvail(void *pvt);
gpHash.h describes a general purpose hash table for character strings. The hash table contains tableSize entries. Each
entry is a list of members that hash to the same value. The user can maintain separate directories which share the same
table by having a different pvt value for each directory.
typedef struct{
ELLNODE node;
const char *name; /*address of name placed in directory*/
void *pvtid; /*private name for subsystem user*/
void *userPvt; /*private for user*/
} GPHENTRY;
struct gphPvt;
/*tableSize must be power of 2 in range 256 to 65536*/
void gphInitPvt(struct gphPvt **ppvt, int tableSize);
GPHENTRY *gphFind(struct gphPvt *pvt, const char *name, void *pvtid);
GPHENTRY *gphAdd(struct gphPvt *pvt, const char *name, void *pvtid);
void gphDelete(struct gphPvt *pvt, const char *name, void *pvtid);
void gphFreeMem(struct gphPvt *pvt);
void gphDump(struct gphPvt *pvt);
void gphDumpFP(FILE *fp, struct gphPvt *pvt);
struct gphPvt *pvt
Together with the program iocLogServer this provides generic support for logging text messages from an IOC or other program to a file on the log server host machine.
A log client runs on the IOC. It accepts string messages and forwards them over a TCP connection to its designated log server (normally running on a host machine).
A log server accepts connections from multiple clients and writes the messages it receives into a rotating file. A log server program ('iocLogServer') is also part of EPICS base.
Configuration of the iocLogServer, as well as the standard iocLogClient that internally uses this library, are described in Section10.7 on page167.
The header file logClient.h exports the following types and routines:
typedef void *logClientId;
An abstract data type, representing a log client.
logClientId logClientCreate (
struct in_addr server_addr, unsigned short server_port);
Create a new log client. Will block the calling task for a maximum of 2 seconds trying to connect to a server with the given ip address and port. If a connection cannot be established, an error message is printed on the console, but the log client will keep trying to connect in the background. This is done by a background task, that will also periodically (every 5 seconds) flush pending messages out to the server.
void logClientSend (logClientId id, const char *message);
Send the given message to the given log client. Messages are not immediately sent to the log server. Instead they are sent whenever the cache overflows, or logClientFlush() is called.
void logClientFlush (logClientId id);
Immediately send all outstanding messages to the server.
void logClientShow (logClientId id, unsigned level);
Print information about the log clients internal state to stdout.
For backward compatibility with older versions of the logClient library, the header file also includes iocLog.h, which exports the definitions for the standard iocLogClient for error logging. See Chapter 10.7.2.
Also for backward compatibility, the following deprecated routines are exported.
logClientId logClientInit (void);
Create a log client that uses the standard ioc log client environment variables (EPICS_IOC_LOG_INET and EPICS_IOC_LOG_PORT) as input to logClientCreate and also registers the log client with the errlog task using errlogAddListener.
void logClientSendMessage (logClientId id, const char *message);
Check the global variable iocLogDisable before calling logClientSend.
macLib.h describes a general purpose macro substitution library.
It is used for all macro substitution in base.
long macCreateHandle(
MAC_HANDLE **handle, /* address of variable to receive pointer */
/* to new macro substitution context */
char *pairs[] /* pointer to NULL-terminated array of */
/* {name,value} pair strings; a NULL */
/* value implies undefined; a NULL */
/* argument implies no macros */
);
void macSuppressWarning(
MAC_HANDLE *handle, /* opaque handle */
int falseTrue /*0 means ussue, 1 means suppress*/
);
/*following returns #chars copied, <0 if any macros are undefined*/
long macExpandString(
MAC_HANDLE *handle, /* opaque handle */
char *src, /* source string */
char *dest, /* destination string */
long maxlen /* maximum number of characters to copy */
/* to destination string */
);
/*following returns length of value */
long macPutValue(
MAC_HANDLE *handle, /* opaque handle */
char *name, /* macro name */
char *value /* macro value */
);
/*following returns #chars copied (<0 if undefined) */
long macGetValue(
MAC_HANDLE *handle, /* opaque handle */
char *name, /* macro name or reference */
char *value, /* string to receive macro value or name */
/* argument if macro is undefined */
long maxlen /* maximum number of characters to copy */
/* to value */
);
long macDeleteHandle(MAC_HANDLE *handle);
long macPushScope(MAC_HANDLE *handle);
long macPopScope(MAC_HANDLE *handle);
long macReportMacros(MAC_HANDLE *handle);
/* Function prototypes (utility library) */
/*following returns #defns encountered; <0 = ERROR */
long macParseDefns(
MAC_HANDLE *handle, /* opaque handle; can be NULL if default */
/* special characters are to be used */
char *defns, /* macro definitions in "a=xxx,b=yyy" */
/* format */
char **pairs[] /* address of variable to receive pointer */
/* to NULL-terminated array of {name, */
/* value} pair strings; all storage is */
/* allocated contiguously */
);
/*following returns #macros defined; <0 = ERROR */
long macInstallMacros(MAC_HANDLE *handle,
char *pairs[] /* pointer to NULL-terminated array of */
/* {name,value} pair strings; a NULL */
/* value implies undefined; a NULL */
/* argument implies no macros */
);
/*Expand string using environment variables as macro definitions */
epicsShareFunc char * /* expanded string; NULL if any undefined macros */
epicsShareAPI macEnvExpand(
char *str /* string to be expanded */
);
NOTE: The directory <base>/src/libCom/macLib contains two files macLibNOTES and macLibREADME that explain this library.
The function prototype for this routine appears in osiSock.h
int aToIPAddr(const char *pAddrString, unsigned short defaultPort,
struct sockaddr_in *pIP);
aToIPAddr() fills in the structure pointed to by the pIP argument with the Internet address and port number specified by the pAddrString argument.
Three forms of pAddrString are accepted:
The Internet address of the host, specified as four (usually decimal) numbers separated by periods.
The Internet address number of the host, specified as a single (usually hexadecimal) number.
The Internet host name of the host.
In all cases the `:p' may be omitted in which case the port number is set to the value of the defaultPort argument. The numbers are normally interpreted in base 16 if they begin with `0x' or `0X', in base 8 if they begin with `0', and in base 10 otherwise. However the numeric forms are interpreted by the operating system's gethostbyname() function, thus the acceptable bases may be OS-specific.
adjustment.h describes a single function:
size_t adjustToWorstCaseAlignment(size_t size);
adjustToWorstCaseAlignment() returns a value >= size that an exact multiple of the worst case alignment for the architecture on which the routine is executed.
cantProceed.h declares routines that are provided for code that can't proceed when an error occurs.
void cantProceed(const char *errorMessage, ...); void *callocMustSucceed(size_t count, size_t size,const char *errorMessage); void *mallocMustSucceed(size_t size, const char *errorMessage);
cantProceed() accepts a printf format string and variable number of arguments; it displays the error message and suspends the current task.
It will never return.
callocMustSucceed() and mallocMustSucceed() can be used in place of calloc() and malloc().
If size or count are zero, or the memory allocation fails, they output a message and call cantProceed().
dbDefs.h includes the C header stddef.h and then defines several generally-useful macros if they have not already been defined:
TRUE - 1
FALSE - 0
NELEMENTS(array) - number of elements in array.
CONTAINER(pointer, structure, member) - returns a pointer to the parent structure given a pointer to a member. The structure argument is a type name, member is the name of the member in that structure that pointer refers to.
LOCAL - synonym for static, deprecated.
OFFSET(structure, member) - synonym for offsetof, deprecated.
epicsConvert.h currently describes:
float epicsConvertDoubleToFloat(double value);
epicsConvertDoubleToFloat converts a double to a float.
If the double value is outside the range that can be represented as a float the value assigned will be FLT_MIN or FLT_MAX with the appropriate matching sign.
A floating exception is never raised.
epicsString.h currently describes:
int epicsStrnRawFromEscaped(char *outbuf, size_t outsize, const char *inbuf,
size_t inlen);
int epicsStrnEscapedFromRaw(char *outbuf, size_t outsize, const char *inbuf,
size_t inlen);
size_t epicsStrnEscapedFromRawSize(const char *inbuf, size_t inlen);
int epicsStrCaseCmp(const char *s1, const char *s2);
int epicsStrnCaseCmp(const char *s1, const char *s2, int n);
char *epicsStrDup(const char *s);
int epicsStrPrintEscaped(FILE *fp, const char *s, int n);
int epicsStrGlobMatch(const char *str, const char *pattern);
char *epicsStrtok_r(char *s, const char *delim, char **lasts);
unsigned int epicsStrHash(const char *str, unsigned int seed);
unsigned int epicsMemHash(const char *str, size_t length,
unsigned int seed);
epicsStrnRawFromEscaped copies the string inbuf to outbuf while substituting C-style escape sequences.
It returns the length of the resultant string (which may contain null bytes).
It will never write more than outsize characters into outbuf or read more than inlen characters from inbuf.
Since the destination string can never be longer than the source, it is legal for inbuf and outbuf to point to the same location and inlen and outsize to have the same value, thus performing the translation in-place.
epicsStrnEscapedFromRaw does the opposite of epicsStrnRawFromEscaped:
non-printable characters are converted into escape sequences.
It returns the number of characters stored in the output buffer, or a value greater than or equal to outsize if the output has been truncated to fit in the specified size.
As the destination string might be larger than the source, in-place translations are not allowed.
The following C-style escaped character constants are output:
\a \b \f \n \r \t \v \\ \' \"
All other non-printable characters appear as:
\ooo
where ooo comprises three octal digits (0-7).
epicsStrnEscapedFromRawSize scans a string that may contain non-printable characters and returns the number of characters needed for the escaped destination buffer.
epicsStrPrintEscaped prints the contents of its input buffer, substituting escape sequences for non-printable characters.
epicsStrCaseCmp and epicsStrnCaseCmp implement strcasecmp and strncasecmp, respectively, which are not available on all operating systems.
They operate like strcmp and strncmp, but are case insensitive.
epicsStrDup implements strdup, which is not available on all operating systems.
It allocates sufficient memory for the string, copies it and returns a pointer to the new copy.
The pointer should eventually be passed to the function free().
If insufficient memory is available cantProceed() is called.
epicsStrGlobMatch returns non-zero if the str matches the shell wild-card pattern.
epicsStrtok_r implements strtok_r, which is not available on all operating systems.
epicsStrHash calculates a hash of a zero-terminated string str, while epicsMemHash uses the same algorithm on a fixed-length memory buffer that may contain zero bytes.
In both cases an initial seed value may be provided which permits multiple strings or buffers to be combined into a single hash result.
The final result should be masked to achieve the desired number of bits in the hash value.
epicsTypes.h provides typedefs for architecture independent data types.
typedef char epicsInt8; typedef unsigned char epicsUInt8; typedef short epicsInt16; typedef unsigned short epicsUInt16; typedef epicsUInt16 epicsEnum16; typedef int epicsInt32; typedef unsigned epicsUInt32; typedef float epicsFloat32; typedef double epicsFloat64; typedef unsigned long epicsIndex; typedef epicsInt32 epicsStatus;
So far the definitions provided in this header file have worked on all architectures.
In addition to the above definitions epicsTypes.h has a number of definitions for displaying the types and other useful definitions.
See the header file for details.
A C++ template for use as an exception object, used inside Channel Access. Not documented here.
This is the header file for the ``decorated names" that appear in header files, e.g.
#define epicsExportSharedSymbols epicsShareFunc int epicsShareAPI a_func(int arg);
Thse are needed to properly create DLLs on windows.
Read the comments in the shareLib.h file for a detailed description of where they should be used.
Note that the epicsShareAPI decorator is deprecated for all new EPICS APIs and is being removed from APIs that are only used within the IOC.
enum TF_RETURN {TF_OK=0, TF_ERROR=1};
TF_RETURN truncateFile (const char *pFileName, unsigned size);
truncateFile() truncates the file to the specified size. truncate() is not used because it is not portable. It returns TF_OK if the file is less than size bytes or if it was successfully truncated. It returns TF_ERROR if the file could not be truncated.
Defines macros OSI_PATH_LIST_SEPARATOR and OSI_PATH_SEPARATOR
The unit test routines make it easy for a test program to generate output that is compatible with the Test Anything Protocol and can thus be used with Perl's automated Test::Harness as well as generating human-readable output. The routines detect whether they are being run automatically and print a summary of the results at the end if not.
void testPlan(int tests); int testOk(int pass, const char *fmt, ...); #define testOk1(cond) testOk(cond, "%s", #cond) void testPass(const char *fmt, ...); void testFail(const char *fmt, ...); int testOkV(int pass, const char *fmt, va_list pvar); void testSkip(int skip, const char *why) void testTodoBegin(const char *why); void testTodoEnd(); int testDiag(const char *fmt, ...); void testAbort(const char *fmt, ...); int testDone(void); typedef int (*TESTFUNC)(void); epicsShareFunc void testHarness(void); epicsShareFunc void runTestFunc(const char *name, TESTFUNC func); #define runTest(func) runTestFunc(#func, func)
A test program starts with a call to testPlan(), announcing how many tests are to be conducted. If this number is not known a value of zero can be used during development, but it is recommended that the correct value be substituted after the test program has been completed.
Individual test results are reported using any of testOk(), testOk1(), testOkV(), testPass() or testFail(). The testOk() call takes and also returns a logical pass/fail result (zero means failure, any other value is success) and a printf-like format string and arguments which describe the test. The convenience macro testOk1() is provided which stringifies its single condition argument, reducing the effort needed when writing test programs. The individual testPass() and testFail() routines can be used when the test program takes a different path on success than on failure, but one or other must always be called for any particular test. The testOkV() routine is a varargs form of testOk() included for internal purposes which may prove useful in some cases.
If some program condition or failure makes it impossible to run some tests, the testSkip() routine can be used to indicate how many tests are being omitted from the run, thus keeping the test counts correct; the constant string why is displayed as an explanation to the user (this string is not printf-like).
If some tests are expected to fail because functionality in the module under test has not yet been fully implemented, these tests may still be executed, wrapped between calls to testTodoBegin() and testTodoEnd(). testTodoBegin() takes a constant string indicating why these tests are not expected to succeed. This modifies the counting of the results so the wrapped tests will not be recorded as failures.
Additional information can be supplied using the testDiag() routine, which displays the relevent information as a comment in the result output. None of the printable strings passed to any testXxx() routine should contain a newline `\n' character, newlines will be added by the test routines as part of the Test Anything Protocol. For multiple lines of diagnostic output, call testDiag() as many times as necessary.
If at any time the test program is unable to continue for some catastrophic reason, calling testAbort() with an appropriate message will ensure that the test harness understands this. testAbort() does not return, but calls the ANSI C routine abort() to cause the program to stop immediately.
After all of the tests have been completed, the return value from testDone() can be used as the return status code from the program's main() routine.
On vxWorks and RTEMS, an alternative test harness can be used to run a series of tests in order and summarize the results from them all at the end just like the Perl harness does. The routine testHarness() is called once at the beginning of the test harness program. Each test program is run by passing its main routine name to the runTest() macro which expands into a call to the runTestFunc() routine. The last test program or the harness program itself must finish by calling epicsExit() which triggers the test summary mechanism to generate its result outputs (from an epicsAtExit callback routine).
To make it easier to create a single test program that can be built for both the embedded and workstation operating system harnesses, the header file testMain.h provides a convenience macro MAIN() that adjusts the name of the test program according to the platform it is running on: main() on workstations and a regular function name on embedded systems.
The following is a simple example of a test program using the epicsUnitTest routines:
#include <math.h>
#include "epicsUnitTest.h"
#include "testMain.h"
MAIN(mathTest)
{
testPlan(3);
testOk(sin(0.0) == 0.0, "Sine starts");
testOk(cos(0.0) == 1.0, "Cosine continues");
if (!testOk1(M_PI == 4.0*atan(1.0)))
testDiag("4*atan(1) = %g", 4.0*atan(1.0));
return testDone();
}
The output from running the above program looks like this:
1..3
ok 1 - Sine starts
ok 2 - Cosine continues
ok 3 - M_PI == 4.0*atan(1.0)
Results
=======
Tests: 3
Passed: 3 = 100%