epics/epics-base
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

Document zero and NaN timeout values

Browse Source 
Rename parameter timeOut => timeout everywhere
This commit is contained in:
Andrew Johnson
2022-01-04 17:16:59 -06:00
parent d1094ee787
commit e4a81bb361
9 changed files with 51 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/ca/src/client/cadef.h
+4 -4
View File
@@ -559,19 +559,19 @@ LIBCA_API chid epicsStdCall ca_evid_to_chid ( evid id );
/*
* ca_pend_event()
*
* timeOut R wait for this delay in seconds
* timeout R wait for this delay in seconds
*/
LIBCA_API int epicsStdCall ca_pend_event (ca_real timeOut);
LIBCA_API int epicsStdCall ca_pend_event (ca_real timeout);
#define ca_poll() ca_pend_event(1e-12)
/*
* ca_pend_io()
*
* timeOut R wait for this delay in seconds but return early
* timeout R wait for this delay in seconds but return early
* if all get requests (or search requests with null
* connection handler pointer have completed)
*/
LIBCA_API int epicsStdCall ca_pend_io (ca_real timeOut);
LIBCA_API int epicsStdCall ca_pend_io (ca_real timeout);
/* calls ca_pend_io() if early is true otherwise ca_pend_event() is called */
LIBCA_API int epicsStdCall ca_pend (ca_real timeout, int early);
modules/libcom/src/osi/epicsEvent.cpp
+2 -2
View File
@@ -70,9 +70,9 @@ void epicsEvent::wait ()
}
}
bool epicsEvent::wait (double timeOut)
bool epicsEvent::wait (double timeout)
{
epicsEventStatus status = epicsEventWaitWithTimeout (this->id, timeOut);
epicsEventStatus status = epicsEventWaitWithTimeout (this->id, timeout);
if (status == epicsEventOK) {
return true;
modules/libcom/src/osi/epicsEvent.h
+8 -4
View File
@@ -99,10 +99,12 @@ public:
**/
void wait ();
/**\brief Wait for the event or until the specified timeout.
* \param timeOut The timeout delay in seconds.
* \param timeout The timeout delay in seconds. A timeout of zero is
* equivalent to calling tryWait(); NaN or any value too large to be
* represented to the target OS is equivalent to no timeout.
* \return True if the event was triggered, False if it timed out.
**/
bool wait ( double timeOut );
bool wait ( double timeout );
/**\brief Similar to wait() except that if the event is currently empty the
* call will return immediately.
* \return True if the event was full (triggered), False if empty.
@@ -190,11 +192,13 @@ LIBCOM_API void epicsEventMustWait(epicsEventId id);
/**\brief Wait an the event or until the specified timeout period is over.
* \note Blocks until full or timeout.
* \param id The event identifier.
* \param timeOut The timeout delay in seconds.
* \param timeout The timeout delay in seconds. A timeout of zero is
* equivalent to calling epicsEventTryWait(); NaN or any value too large
* to be represented to the target OS is equivalent to no timeout.
* \return Status indicator.
**/
LIBCOM_API epicsEventStatus epicsEventWaitWithTimeout(
epicsEventId id, double timeOut);
epicsEventId id, double timeout);
/**\brief Similar to wait() except that if the event is currently empty the
* call will return immediately with status \c epicsEventWaitTimeout.
modules/libcom/src/osi/epicsMessageQueue.h
+12 -5
View File
@@ -84,6 +84,9 @@ public:
/**
* \brief Send a message or timeout.
* \param timeout The timeout delay in seconds. A timeout of zero is
* equivalent to calling trySend(); NaN or any value too large to be
* represented to the target OS is equivalent to no timeout.
* \returns 0 if the message was sent to a receiver or queued for
* future delivery.
* \returns -1 if the timeout was reached before the
@@ -124,12 +127,16 @@ public:
int receive ( void *message, unsigned int size );
/**
* \brief Wait for a message to be queued.
* Wait up to \p timeout seconds for a message to be sent if the queue
* is empty, then move the first message to the specified location.
* \brief Wait for and fetch the next message.
* \param timeout The timeout delay in seconds. A timeout of zero is
* equivalent to calling tryReceive(); NaN or any value too large to
* be represented to the target OS is equivalent to no timeout.
*
* If the received message is larger than the specified
* messageBufferSize it may either return -1, or truncate the
* Waits up to \p timeout seconds for a message to arrive if the queue
* is empty, then moves the first message to the specified location.
*
* If the received message is larger than the specified message size
* the implementation may either return -1, or truncate the
* message. It is most efficient if the messageBufferSize is equal
* to the maximumMessageSize with which the message queue was
* created.
modules/libcom/src/osi/os/RTEMS-posix/osdEvent.c
+6 -6
View File
@@ -62,7 +62,7 @@ epicsEventWait(epicsEventId pSem)
}
LIBCOM_API epicsEventStatus
epicsEventWaitWithTimeout(epicsEventId pSem, double timeOut)
epicsEventWaitWithTimeout(epicsEventId pSem, double timeout)
{
int sc;
rtems_interval delay;
@@ -71,22 +71,22 @@ epicsEventWaitWithTimeout(epicsEventId pSem, double timeOut)
if (!rate)
return epicsEventError;
if (timeOut <= 0.0) {
if (timeout <= 0.0) {
sc = rtems_binary_semaphore_try_wait(&pSem->rbs);
if (!sc)
return epicsEventOK;
else
return epicsEventWaitTimeout;
}
else if (timeOut < (double) UINT32_MAX / rate) {
delay = timeOut * rate;
else if (timeout < (double) UINT32_MAX / rate) {
delay = timeout * rate;
if (delay == 0) {
/* 0 < timeOut < 1/rate; round up */
/* 0 < timeout < 1/rate; round up */
delay = 1;
}
}
else {
/* timeOut is NaN or too big to represent; wait forever */
/* timeout is NaN or too big to represent; wait forever */
delay = RTEMS_NO_TIMEOUT;
}
modules/libcom/src/osi/os/RTEMS-score/osdEvent.c
+3 -3
View File
@@ -122,17 +122,17 @@ epicsEventWait(epicsEventId id)
}
epicsEventStatus
epicsEventWaitWithTimeout(epicsEventId id, double timeOut)
epicsEventWaitWithTimeout(epicsEventId id, double timeout)
{
rtems_id sid = (rtems_id)id;
rtems_status_code sc;
rtems_interval delay;
extern double rtemsTicksPerSecond_double;
if (timeOut <= 0.0)
if (timeout <= 0.0)
return epicsEventTryWait(id);
SEMSTAT(1)
delay = timeOut * rtemsTicksPerSecond_double;
delay = timeout * rtemsTicksPerSecond_double;
if (delay == 0)
delay++;
sc = rtems_semaphore_obtain (sid, RTEMS_WAIT, delay);
modules/libcom/src/osi/os/WIN32/osdEvent.c
+4 -4
View File
@@ -90,7 +90,7 @@ LIBCOM_API epicsEventStatus epicsEventWait ( epicsEventId pSem )
* epicsEventWaitWithTimeout ()
*/
LIBCOM_API epicsEventStatus epicsEventWaitWithTimeout (
epicsEventId pSem, double timeOut )
epicsEventId pSem, double timeout )
{
/* waitable timers use 100 nanosecond intervals, like FILETIME */
static const unsigned ivalPerSec = 10000000u; /* number of 100ns intervals per second */
@@ -101,17 +101,17 @@ LIBCOM_API epicsEventStatus epicsEventWaitWithTimeout (
HANDLE timer;
LONGLONG nIvals; /* number of intervals */
if ( timeOut <= 0.0 ) {
if ( timeout <= 0.0 ) {
tmo.QuadPart = 0u;
}
else if ( timeOut >= INFINITE / mSecPerSec ) {
else if ( timeout >= INFINITE / mSecPerSec ) {
/* we need to apply a maximum wait time to stop an overflow. We choose (INFINITE - 1) milliseconds,
to be compatible with previous WaitForSingleObject() implementation */
nIvals = (LONGLONG)(INFINITE - 1) * (ivalPerSec / mSecPerSec);
tmo.QuadPart = -nIvals; /* negative value means a relative time offset for timer */
}
else {
nIvals = (LONGLONG)(timeOut * ivalPerSec + 0.999999);
nIvals = (LONGLONG)(timeout * ivalPerSec + 0.999999);
tmo.QuadPart = -nIvals;
}
modules/libcom/src/osi/os/vxWorks/osdEvent.c
+6 -6
View File
@@ -34,24 +34,24 @@ void epicsEventDestroy(epicsEventId id)
semDelete((SEM_ID)id);
}
epicsEventStatus epicsEventWaitWithTimeout(epicsEventId id, double timeOut)
epicsEventStatus epicsEventWaitWithTimeout(epicsEventId id, double timeout)
{
int rate = sysClkRateGet();
int status;
int ticks;
if (timeOut <= 0.0) {
if (timeout <= 0.0) {
ticks = 0;
}
else if (timeOut < (double) INT_MAX / rate) {
ticks = timeOut * rate;
else if (timeout < (double) INT_MAX / rate) {
ticks = timeout * rate;
if (ticks == 0) {
/* 0 < timeOut < 1/rate; round up */
/* 0 < timeout < 1/rate; round up */
ticks = 1;
}
}
else {
/* timeOut is NaN or too big to represent in ticks */
/* timeout is NaN or too big to represent in ticks */
ticks = WAIT_FOREVER;
}
status = semTake((SEM_ID)id, ticks);
modules/libcom/src/osi/os/vxWorks/osdMessageQueue.cpp
+6 -6
View File
@@ -30,15 +30,15 @@ LIBCOM_API int epicsStdCall epicsMessageQueueSendWithTimeout(
if (timeout <= 0.0) {
ticks = 0;
}
else if (timeOut < (double) INT_MAX / rate) {
else if (timeout < (double) INT_MAX / rate) {
ticks = timeout * rate;
if (ticks == 0) {
/* 0 < timeOut < 1/rate; round up */
/* 0 < timeout < 1/rate; round up */
ticks = 1;
}
}
else {
/* timeOut is NaN or too big to represent in ticks */
/* timeout is NaN or too big to represent in ticks */
ticks = WAIT_FOREVER;
}
@@ -57,15 +57,15 @@ LIBCOM_API int epicsStdCall epicsMessageQueueReceiveWithTimeout(
if (timeout <= 0.0) {
ticks = 0;
}
else if (timeOut < (double) INT_MAX / rate) {
else if (timeout < (double) INT_MAX / rate) {
ticks = timeout * rate;
if (ticks == 0) {
/* 0 < timeOut < 1/rate, round up */
/* 0 < timeout < 1/rate, round up */
ticks = 1;
}
}
else {
/* timeOut is NaN or too big to represent in ticks */
/* timeout is NaN or too big to represent in ticks */
ticks = WAIT_FOREVER;
}