Rule-Based Thread Properties

Allow user-specified rules that modify real-time properties of EPICS threads. More...

Files
file	threadRules.c
	Rule-based modification of thread real-time properties.

Functions
epicsShareFunc void	mcoreThreadModify (epicsThreadId id, const char *policy, const char *priority, const char *cpus)
	iocShell: Modify a thread's real-time properties.
epicsShareFunc void	mcoreThreadRulesInit ()
	Initialization routine.
epicsShareFunc long	mcoreThreadRuleAdd (const char *name, const char *policy, const char *priority, const char *cpus, const char *pattern)
	iocShell: Add or replace a thread rule.
epicsShareFunc void	mcoreThreadRuleDelete (const char *name)
	iocShell: Delete a thread rule.
epicsShareFunc void	mcoreThreadRulesShow (void)
	iocShell: Print a comprehensive list of the thread rules.

Detailed Description

Allow user-specified rules that modify real-time properties of EPICS threads.

Implements a library that uses rules to modify real-time properties of EPICS threads:

• Scheduling policy
  Scheduling mechanism used for this thread. When POSIX scheduling is enabled, the default mechanism is SCHED_FIFO, but SCHED_OTHER and SCHED_RR are also supported.
• Scheduling priority
  OSI priority value that gets converted to the system's real-time priority schema.
• CPU Affinity
  Set of CPUs that this thread is allowed to run on.

This is achieved by creating a linked list of rules, which consist of a regular expression pattern and modification instructions. A hook function is added to the EPICS thread creation module. The hook is called from every thread as part of its creation, matches the regular expression patterns of all rules against the name of the newly created thread, and applies the modifications of all rules that match.

See man pages for pthread_setschedparam(3) and sched_setscheduler(2) for details on scheduling policy and priority, pthread_setaffinity_np(3) and sched_setaffinity(2) for details on CPU affinity.

Configuration Files

The module tries to read a system configuration file (/etc/rtrules) and a user configuration file (default: $HOME/.rtrules) to create the initial list of thread rules.

The file format is based on the format of the /etc/rtgroups file on RHEL-MRG. Each line has the format

name:policy:priority:affinity:pattern

name	name of the rule
policy	scheduling policy to set for the thread (first letter, not case sensitive), * = don't change
priority	scheduling priority to set for the thread (a + or - sign adds to the current priority), * = don't change
affinity	CPUs to set the thread's affinity to (use , and - to specify multiple CPUs and ranges, e.g. 0,3-5), * = don't change
pattern	regular expression pattern to match thread names against, see man page for regex(7) for details

Lines starting with # (comments), and empty lines (containing only whitespace) are ignored.

Environment Variables

HOME

location of the HOME directory (default: /)

EPICS_MCORE_USERCONFIG

name of user configuration file, relative to the HOME directory (default: .rtrules)

Linux Security

To change its scheduling policy and priority, under modern Linux systems the process must have an rtprio entry in the pam limits module configuration.

See the limits.conf(5) man page for details.

Known Issues

A thread calling epicsThreadSetPriority() to set its priority while running may override the priorities defined in the rules at any time.

Function Documentation

epicsShareFunc void mcoreThreadModify	(	epicsThreadId	id,
		const char *	policy,
		const char *	priority,
		const char *	cpus
	)

iocShell: Modify a thread's real-time properties.

Parameters

id	EPICS thread id
policy	scheduling policy to set (* = don't change)
priority	scheduling priority (OSI) to set (a + or - sign adds to the current priority, * = don't change)
cpus	cpuset specification to set (use , and - to specify multiple CPUs and ranges, * = don't change)

IOC Shell

mcoreThreadModify thread policy priority cpus

thread	thread name or id
policy	scheduling policy to set (* = don't change)
priority	scheduling priority (OSI) to set (a + or - sign adds to the current priority, * = don't change)
cpus	cpuset specification to set (use , and - to specify multiple CPUs and ranges, * = don't change)

Definition at line 289 of file threadRules.c.

epicsShareFunc long mcoreThreadRuleAdd	(	const char *	name,
		const char *	policy,
		const char *	priority,
		const char *	cpus,
		const char *	pattern
	)

iocShell: Add or replace a thread rule.

Parameters

name	rule name (identifier)
policy	scheduling policy to set (* = don't change)
priority	scheduling priority (OSI) to set (a + or - sign adds to the current priority, * = don't change)
cpus	cpuset specification to set (use , and - to specify multiple CPUs and ranges, * = don't change)
pattern	regex(7) pattern to match thread names against

Returns

(OK, ERROR) as (0,-1)

IOC Shell

mcoreThreadRuleAdd name policy priority cpus pattern

name	rule name (identifier)
policy	scheduling policy to set (* = don't change)
priority	scheduling priority (OSI) to set (a + or - sign adds to the current priority, * = don't change)
cpus	cpuset specification to set (use , and - to specify multiple CPUs and ranges, * = don't change)
pattern	regex(7) pattern to match thread names against

Definition at line 109 of file threadRules.c.

epicsShareFunc void mcoreThreadRuleDelete

(

const char *

name

)

iocShell: Delete a thread rule.

Parameters

name	name (identifier) of the rule to delete

IOC Shell

mcoreThreadRuleDelete name

name	name (identifier) of the rule to delete

Definition at line 140 of file threadRules.c.

epicsShareFunc void mcoreThreadRulesInit

(

)

Initialization routine.

Must be called before using any of the other functions, which is done when registering the iocsh commands.

Definition at line 377 of file threadRules.c.

epicsShareFunc void mcoreThreadRulesShow

(

void

)

iocShell: Print a comprehensive list of the thread rules.

Rule names are shortened to 16 characters.

IOC Shell

mcoreThreadRulesShow

Definition at line 165 of file threadRules.c.