From e5782ae716ea60f721ed0545d60412dcb68db5e5 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 2 Jul 2019 17:38:16 -0500 Subject: [PATCH] Update release notes again, more detail --- documentation/RELEASE_NOTES.html | 95 +++++++++++++++++++++++--------- 1 file changed, 70 insertions(+), 25 deletions(-) diff --git a/documentation/RELEASE_NOTES.html b/documentation/RELEASE_NOTES.html index b3e266031..203b7a873 100644 --- a/documentation/RELEASE_NOTES.html +++ b/documentation/RELEASE_NOTES.html @@ -26,42 +26,87 @@ release.

--> -

VxWorks Minimum Version Requirements

+

VxWorks Minimum Version Recommendation

-

The implementation of the epicsThreadMustJoin() functionality -described below requires facilities that were added to the OS in VxWorks 6.9, so -that is now the oldest version which this release of EPICS can be built -against.

+

The implementation of the epicsThreadMustJoin() feature +described below uses facilities that were added to VxWorks in version 6.9. When +built against an older version of VxWorks the join functionality will not be +available and calls to epicsThreadMustJoin() will return +immediately. In this case the epicsThread.h header will not define the C macro +EPICS_THREAD_CAN_JOIN to allow alternate code to be provided for +these targets. The IOC's use of the join feature has been designed to work for +either situation.

-

Add epicsThreadCreateOpt() and epicsThreadMustJoin()

-

epicsThreadCreateOpt() is an alternative to epicsThreadCreate() which -passes some arguments via a structure (struct epicsThreadOpts). -This epicsThreadOpts* may be NULL to use target specific -defaults. Caller wishing to provide thread options should first call -epicsThreadOptsDefaults() to fill in the defaults.

+

New and modified epicsThread APIs

+ +

epicsThreadCreateOpt()

+ +

A new routine epicsThreadCreateOpt() is an alternative to +epicsThreadCreate() which takes some arguments via a structure +(struct epicsThreadOpts) to allow for future extensions.

+ +
+typedef struct epicsThreadOpts {
+    unsigned int priority;
+    unsigned int stackSize;
+    unsigned int joinable;
+} epicsThreadOpts;
+#define EPICS_THREAD_OPTS_INIT { \
+    epicsThreadPriorityLow, epicsThreadStackMedium, 0}
+
+epicsThreadId epicsThreadCreateOpt(const char * name,
+    EPICSTHREADFUNC funptr, void * parm, const epicsThreadOpts *opts);
+
+ +

The final opts parameter may be NULL to use the +default values of thread priority (low) and stack size (medium). Callers wishing +to provide alternative settings for these thread options or to create a joinable +thread (see below) should create and pass in an epicsThreadOpts +structure as shown below. Always initialize one of these structures using the +EPICS_THREAD_OPTS_INIT macro to ensure that any additional fields +that get added in the future are set to their default values.

 void startitup(void) {
-    epicsThreadOpts opts;
-    epicsThreadOptsDefaults(&opts);
-    opts.priority = epicsThreadPriorityMedium;
+    epicsThreadOpts opts = EPICS_THREAD_OPTS_INIT;
+    epicsThreadId tid;
 
-    ... = epicsThreadCreateOpt("my thread", &threadMain, NULL, &opts);
+    opts.priority = epicsThreadPriorityMedium;
+    tid = epicsThreadCreateOpt("my thread", &threadMain, NULL, &opts);
 }
-

If the new epicsThreadOpts::joinable option flag is set (not the default), -then epicsThreadMustJoin() must be called with that -thread's epicsThreadId when/after the thread exits, to free up thread resources. -This function will block until the thread's main function has returned, after -which the epicsThreadId will no longer be valid.

+

C or C++ Code that also needs to build on earlier versions of Base can use +#ifdef EPICS_THREAD_OPTS_INIT to determine whether the +epicsThreadCreateOpt() API is available on this Base version.

+ +

Thread stack sizes

+ +

The stackSize member of the epicsThreadOpts +structure and the equivalent parameters to the epicsThreadCreate() +and epicsThreadMustCreate() routines can now be passed either one +of the epicsThreadStackSizeClass enum values or a value returned +from the epicsThreadGetStackSize() routine.

+ +

epicsThreadMustJoin()

+ +

If the new joinable flag of an epicsThreadOpts +structure is non-zero (the default value is zero), the new API routine +epicsThreadMustJoin() must be called with the thread's +epicsThreadId when/after the thread exits, to free up thread +resources. This function will block until the thread's main function has +returned, allowing the parent to wait for its child thread. The child's +epicsThreadId will no longer be valid and should not be used after +the epicsThreadMustJoin() routine returns.

+ +

A thread that was originally created with its joinable flag set may itself +call epicsThreadMustJoin(), passing in its own epicsThreadId. This +marks the thread as no longer being joinable, so it will then free the thread +resources itself when its main function returns. The epicsThreadId +of a thread that is not joinable gets invalidated as soon as its main function +returns.

-

A thread which was created with the joinable flag set may itself call -epicsThreadMustJoin() passing its own epicsThreadId. This marks the -thread as no longer being joinable, so it will then free the thread resources -itself when its main function returns. The epicsThreadId for a thread that is -not joinable gets invalidated as soon as its main function returns.

Launchpad Bugs