Pthread

Description

manage pthreads and process niceness

<rc/pthread.h>

Author

James Strawson

Date

1/19/2018

Functions
int	rc_pthread_create (pthread_t *thread, void *(*func)(void *), void *arg, int policy, int priority)
	starts a pthread with specified policy and priority More...
int	rc_pthread_timed_join (pthread_t thread, void **retval, float timeout_sec)
	Joins a thread with timeout given in seconds. More...
int	rc_pthread_print_properties (pthread_t thread)
	Prints human-readable scheduler and priority for a pthread_t handle. More...
int	rc_pthread_set_properties_self (int policy, int priority)
	Lets a thread change it's own scheduler policy and priority while running. More...
int	rc_pthread_get_process_niceness (void)
	fetches the niceness value of the executing process More...
int	rc_pthread_set_process_niceness (int niceness)
	Lets a process change its own niceness value. More...

Function Documentation

rc_pthread_create()

int rc_pthread_create	(	pthread_t *	thread,
		void *(*)(void *)	func,
		void *	arg,
		int	policy,
		int	priority
	)

starts a pthread with specified policy and priority

Note that using anything other than SCHED_OTHER with priority 0 is only available to root users or after giving special permission to the executable with the setcap command line utility.

If a policy is selected which requires privaldges the user does not have, then a friendly warning will be displayed and the thread will still be set with the priority and scheduler inherited from the calling process.

Parameters

	thread	pointer to user's pthread_t handle
	func	function pointer for thread to start
	arg	argument to pass to thread function when it starts
[in]	policy	SCHED_FIFO SCHED_RR or SCHED_OTHER
[in]	priority	between 1-99 for FIFO and RR, defualt 0 for SCHED_OTHER

Returns

0 on success or -1 on error

Examples:

rc_balance.c, rc_calibrate_escs.c, and rc_test_pthread.c.

rc_pthread_timed_join()

int rc_pthread_timed_join	(	pthread_t	thread,
		void **	retval,
		float	timeout_sec
	)

Joins a thread with timeout given in seconds.

If no timeout is necessary, just use the standard system pthread_join function.

Parameters

[in]	thread	pthread_t handle
	retval	place to put the exit status of target thread, see pthread_join
[in]	timeout_sec	floating point timeout in seconds

Returns

Returns 0 if the thread joined within the timeout period, 1 if the thread timed out and was forced to close, -1 on error.

Examples:

rc_balance.c, rc_calibrate_escs.c, and rc_test_pthread.c.

rc_pthread_print_properties()

int rc_pthread_print_properties

(

pthread_t

thread

)

Prints human-readable scheduler and priority for a pthread_t handle.

Parameters

[in]

thread

pthread_t handle

Returns

0 on success or -1 on failure

Examples:

rc_test_pthread.c.

rc_pthread_set_properties_self()

int rc_pthread_set_properties_self	(	int	policy,
		int	priority
	)

Lets a thread change it's own scheduler policy and priority while running.

Parameters

[in]	policy	SCHED_FIFO SCHED_RR or SCHED_OTHER
[in]	priority	between 1-99 for FIFO and RR, defualt 0 for SCHED_OTHER

Returns

0 on success or -1 on failure

rc_pthread_get_process_niceness()

int rc_pthread_get_process_niceness

(

void

)

fetches the niceness value of the executing process

This is just a helpful wrapper for the system getpriority function and returns the same value.

Returns

niceness (-20 to 20) or -1 on failure and sets errno

Examples:

rc_test_pthread.c.

rc_pthread_set_process_niceness()

int rc_pthread_set_process_niceness

(

int

niceness

)

Lets a process change its own niceness value.

Note that this requires special privaledges and will print an error if run by a normal user. This is just a helpful wrapper for the system setpriority funtion and returns the same thing.

Parameters

[in]

niceness

new niceness (-20 to 20)

Returns

0 on success, -1 on failure