QoS Resource Reservation Library
[QoS Resource Reservation]

Allows applications to take advantage of Resource Reservation scheduling services available within the kernel when the QoS Resource Reservation Kernel Module module is loaded. More...

Files
file	qres_lib.h
	QRES Library Application Programming Interface.
file	qres_gw.h
	Common defines for the US to KS gateway.
Functions
qos_rv	qres_init (void)
	Initializes the QoS RES library.
qos_rv	qres_cleanup (void)
	Cleanup resources associated to the QoS RES Library.
qos_rv	qres_create_server (qres_params_t *p_params, qres_sid_t *p_sid)
	: in the following functions, if pid == 0 -> apply to itself
qos_rv	qres_attach_thread (qres_sid_t server_id, pid_t pid, tid_t tid)
	Attach a task to an already existing server.
qos_rv	qres_detach_thread (qres_sid_t sid, pid_t pid, tid_t tid)
	Detach from the QoS Server and possibly destroy it.
qos_rv	qres_destroy_server (qres_sid_t sid)
	Detach all processes from a server and destroy it.
qos_rv	qres_get_sid (pid_t pid, tid_t tid, qres_sid_t *p_sid)
	Get a thread server id, or QOS_E_NOT_FOUND if it is not attached to any server.
qos_rv	qres_set_bandwidth (qres_sid_t sid, qos_bw_t bw)
	Change bandwidth.
qos_rv	qres_get_params (qres_sid_t sid, qres_params_t *p_params)
	Retrieve QoS scheduling parameters.
qos_rv	qres_set_params (qres_sid_t sid, qres_params_t *p_params)
	Change QoS scheduling parameters.
qos_rv	qres_get_bandwidth (qres_sid_t sid, float *bw)
	Get the bandwidth of the server with the supplied ID.
qos_rv	qres_module_exists ()
	Detect module in /proc/modules.
qos_rv	qres_get_exec_time (qres_sid_t sid, qres_time_t *exec_time, qres_atime_t *abs_time)
	Retrieve time info relative to the current server.
qos_rv	qres_get_curr_budget (qres_sid_t sid, qres_time_t *curr_budget)
	Retrieve remaining budget for the current server instance.
qos_rv	qres_get_next_budget (qres_sid_t sid, qres_time_t *next_budget)
	Retrieve the budget that is likely to be used for the very next server instance.
qos_rv	qres_get_appr_budget (qres_sid_t sid, qres_time_t *appr_budget)
	Retrieve the budget that has been approved for the subsequent server instances.
qos_rv	qres_get_deadline (qres_sid_t sid, struct timespec *p_deadline)
	Retrieve current scheduling deadline.
qos_rv	qres_set_weight (qres_sid_t sid, unsigned int weight)
	Set scheduling weight (i.e., used by shrub).
qos_rv	qres_get_weight (qres_sid_t sid, unsigned int *p_weight)
	Retrieve scheduling weight (i.e., used by shrub).
qos_rv	qres_get_servers (qres_sid_t *sids, size_t *p_num_sids)
	Retrieve the existing servers.

---

Detailed Description

Allows applications to take advantage of Resource Reservation scheduling services available within the kernel when the QoS Resource Reservation Kernel Module module is loaded.

---

Function Documentation

qos_rv qres_attach_thread	(	qres_sid_t	server_id,
		pid_t	pid,
		tid_t	tid
	)

Attach a task to an already existing server.

Parameters:

	pid	The process ID of the task to affect, or zero for the current process
	tid	The thread ID of the thread to affect, or zero for the current thread (only valid if pid is zero as well)
	server_id	The identifier of the server to which the task has to be attached

Definition at line 104 of file qres_lib.c.

References check_open(), IOCTL_OP_ATTACH_TO_SERVER, qres_attach_iparams_t::pid, qos_chk_rv, qos_int_rv, QOS_OK, qres_fd, qres_attach_iparams_t::server_id, and qres_attach_iparams_t::tid.

Referenced by main(), main_body(), and main_loop().

qos_rv qres_cleanup

(

void

)

Cleanup resources associated to the QoS RES Library.

After this call, it is not possible to use any qres_xx() call

Definition at line 150 of file qres_lib.c.

qos_rv qres_create_server	(	qres_params_t *	p_params,
		qres_sid_t *	p_sid
	)

: in the following functions, if pid == 0 -> apply to itself

Create a new server with specified parameters.

Change scheduling policy of the specified process to benefit of QoS support into the kernel with provided parameters.

Parameters:

	p_params	If the QRES_F_PERSISTENT flag is set in p_params->flags, then the server is not automatically destroyed after detach of the last thread. Instead, it keeps existing, where further threads may be attached to it by using the a qres_sid_t value for identification.
	p_sid	Pointer to a qres_sid_t variable that is filled with the server ID of the created server. This ID is needed to perform any further operation on the created server (attaching/detaching threads, getting or setting parameters, destroying the server).

Note:

If the QRES_WATCHDOG has been enabled in the module configuration, then, if a persistent server remains empty (with no attached threads) for too much time, the system destroys it automatically. This is a precaution for avoiding persistence of "unreachable" servers in the system, due to programming bugs or application crashes.

Todo:

Implement the QRES_WATCHDOG feature.

Definition at line 74 of file qres_lib.c.

qos_rv qres_destroy_server

(

qres_sid_t

sid

)

Detach all processes from a server and destroy it.

Detach all attached threads from a QRES server, then destroy it. This causes the QRES system to free any resources previously associated to the destroyed server, and to the attached tasks, if any.

Note:

After a successfull completition of this call, the specified server ID is not valid anymore. Though, it may be reused later by the system to identify a new server created subsequently through a qres_create_server() call.

Definition at line 93 of file qres_lib.c.

References check_open(), IOCTL_OP_DESTROY_SERVER, qos_chk_rv, qos_int_rv, QOS_OK, and qres_fd.

Referenced by main(), main_body(), main_loop(), qos_func_define(), and qres_cleanup().

qos_rv qres_detach_thread	(	qres_sid_t	sid,
		pid_t	pid,
		tid_t	tid
	)

Detach from the QoS Server and possibly destroy it.

Detach the specified process from the QoS server and return the scheduling policy to the standard default system scheduler behaviour. If no more processes reside in the server, destroy resources associated to it.

For parameters specification, please see qres_attach_to_server()

See also:

qres_attach_to_server()

Definition at line 121 of file qres_lib.c.

References check_open(), IOCTL_OP_DETACH_FROM_SERVER, qres_attach_iparams_t::pid, qos_chk_rv, qos_int_rv, QOS_OK, qres_fd, qres_attach_iparams_t::server_id, and qres_attach_iparams_t::tid.

Referenced by main().

qos_rv qres_get_appr_budget	(	qres_sid_t	sid,
		qres_time_t *	appr_budget
	)

Retrieve the budget that has been approved for the subsequent server instances.

Whenever a change of budget is requested, either as a result of a qres_set_params() or as a result of the creation of a new server, each server that has been approved a budget increase from the supervisor may undergo (if such increase in not immediately and entirely available) a transitory period during which the current budget, as returned by qres_get_curr_budget(), may change multiple times, until it reaches the approved value.

Definition at line 237 of file qres_lib.c.

References check_open(), qres_time_iparams_t::exec_time, IOCTL_OP_GET_APPR_BUDGET, qos_chk_ok_do, QOS_E_INVALID_PARAM, qos_int_rv, qos_log_err, QOS_OK, qos_strerror(), qres_fd, and qres_time_iparams_t::server_id.

Referenced by f(), main(), and qos_func_define().

qos_rv qres_get_bandwidth	(	qres_sid_t	sid,
		float *	bw
	)

Get the bandwidth of the server with the supplied ID.

Definition at line 310 of file qres_lib.c.

References check_open(), IOCTL_OP_GET_PARAMS, qres_params_t::P, qres_iparams_t::params, qres_params_t::Q, qos_chk_ok_ret, qos_int_rv, QOS_OK, qres_fd, and qres_iparams_t::server_id.

qos_rv qres_get_curr_budget	(	qres_sid_t	sid,
		qres_time_t *	curr_budget
	)

Retrieve remaining budget for the current server instance.

Definition at line 199 of file qres_lib.c.

References check_open(), qres_time_iparams_t::exec_time, IOCTL_OP_GET_CURR_BUDGET, qos_chk_ok_do, QOS_E_INVALID_PARAM, qos_int_rv, qos_log_err, QOS_OK, qos_strerror(), qres_fd, and qres_time_iparams_t::server_id.

Referenced by f(), main(), and qos_func_define().

qos_rv qres_get_deadline	(	qres_sid_t	sid,
		struct timespec *	p_deadline
	)

Retrieve current scheduling deadline.

Definition at line 325 of file qres_lib.c.

References check_open(), IOCTL_OP_GET_DEADLINE, qos_chk_ok_do, QOS_E_INVALID_PARAM, qos_int_rv, qos_log_err, QOS_OK, qos_strerror(), qres_fd, qres_timespec_iparams_t::server_id, and qres_timespec_iparams_t::timespec.

Referenced by qos_func_define().

qos_rv qres_get_exec_time	(	qres_sid_t	sid,
		qres_time_t *	exec_time,
		qres_atime_t *	abs_time
	)

Retrieve time info relative to the current server.

Parameters:

	exec_time	If non-null, returns the sum of the execution times of all the processes belonging to the same server as the one identified by the sid parameter, measured since the call to * qres_create_server()
	abs_time	If non-null, returns the absolute time, measured since some fixed point in the past (e.g. machine boot)

Todo:

specify better the time-reference of abs_time, so that it may be used together with standard timer-related POSIX calls from user-space

Returns:

The server execution time, of one of the QOS_E_ error codes if negative.

Definition at line 180 of file qres_lib.c.

References qres_time_iparams_t::abs_time, check_open(), qres_time_iparams_t::exec_time, IOCTL_OP_GET_EXEC_TIME, qos_chk_rv, qos_int_rv, qos_log_err, QOS_OK, qos_strerror(), qres_fd, and qres_time_iparams_t::server_id.

Referenced by main(), main_body(), and main_loop().

qos_rv qres_get_next_budget	(	qres_sid_t	sid,
		qres_time_t *	next_budget
	)

Retrieve the budget that is likely to be used for the very next server instance.

The value returned by this function may change asynchronously from, and in a way that depends on, the bandwidth changes requested on all the servers in the system.

Definition at line 218 of file qres_lib.c.

References check_open(), qres_time_iparams_t::exec_time, IOCTL_OP_GET_NEXT_BUDGET, qos_chk_ok_do, QOS_E_INVALID_PARAM, qos_int_rv, qos_log_err, QOS_OK, qos_strerror(), qres_fd, and qres_time_iparams_t::server_id.

Referenced by f(), main(), and qos_func_define().

qos_rv qres_get_params	(	qres_sid_t	sid,
		qres_params_t *	p_params
	)

Retrieve QoS scheduling parameters.

The returned values may be slightly different than those set through qres_set_params().

Note:

Returned budget values may be slightly higher than the ones set through qres_init_server() or qres_set_params(), because any granted (budget, period) pair corresponds to a qos_bw_t value (fixed-point representation of the ratio budget/period).

Definition at line 274 of file qres_lib.c.

References check_open(), IOCTL_OP_GET_PARAMS, qres_iparams_t::params, qos_chk_rv, qos_int_rv, QOS_OK, qres_fd, and qres_iparams_t::server_id.

Referenced by f(), main(), and qos_func_define().

qos_rv qres_get_servers	(	qres_sid_t *	sids,
		size_t *	p_num_sids
	)

Retrieve the existing servers.

Parameters:

	sids	A pre-allocated array supplied by the caller for storing the server ids
	p_num_sids	An I/O parameter: the caller supplies the maximum number of server that can be stored in the sids[] array, the function returns the number of actually filled vector entries.

Note:

If the caller finds *p_num_sids untouched, and the function returned QOS_OK, then the number of existing servers may actually be higher.

Definition at line 378 of file qres_lib.c.

References QOS_E_MISSING_COMPONENT, qos_log_err, and QOS_OK.

qos_rv qres_get_sid	(	pid_t	pid,
		tid_t	tid,
		qres_sid_t *	p_sid
	)

Get a thread server id, or QOS_E_NOT_FOUND if it is not attached to any server.

Definition at line 56 of file qres_lib.c.

References check_open(), IOCTL_OP_GET_SERVER_ID, qres_attach_iparams_t::pid, qos_chk_rv, qos_int_rv, QOS_OK, qres_fd, qres_attach_iparams_t::server_id, and qres_attach_iparams_t::tid.

Referenced by main().

qos_rv qres_get_weight	(	qres_sid_t	sid,
		unsigned int *	p_weight
	)

Retrieve scheduling weight (i.e., used by shrub).

Definition at line 360 of file qres_lib.c.

References check_open(), IOCTL_OP_GET_WEIGHT, qos_chk_ok_do, QOS_E_INVALID_PARAM, qos_int_rv, qos_log_err, QOS_OK, qos_strerror(), qres_fd, qres_weight_iparams_t::server_id, and qres_weight_iparams_t::weight.

qos_rv qres_init

(

void

)

Initializes the QoS RES library.

Checks that the kernel supports QoS Management, then initializes the QRES library.

Returns:

QOS_OK if initialization was succesful QOS_E_MISSING_COMPONENT if kernel does not support QoS management

Definition at line 140 of file qres_lib.c.

qos_rv qres_module_exists

(

)

Detect module in /proc/modules.

Definition at line 164 of file qres_lib.c.

References QOS_E_GENERIC, and QOS_OK.

qos_rv qres_set_bandwidth	(	qres_sid_t	sid,
		qos_bw_t	bw
	)

Change bandwidth.

Definition at line 291 of file qres_lib.c.

References bw2Q(), check_open(), IOCTL_OP_SET_PARAMS, qres_params_t::P, qres_iparams_t::params, qres_params_t::Q, qos_chk_rv, qos_int_rv, qos_log_debug, QOS_OK, qos_strerror(), qres_fd, and qres_iparams_t::server_id.

qos_rv qres_set_params	(	qres_sid_t	sid,
		qres_params_t *	p_params
	)

Change QoS scheduling parameters.

Definition at line 256 of file qres_lib.c.

References check_open(), IOCTL_OP_SET_PARAMS, qres_iparams_t::params, qos_chk_rv, qos_int_rv, QOS_OK, qres_fd, and qres_iparams_t::server_id.

Referenced by job_fn(), job_fn_setup(), main(), main_loop(), and qos_func_define().

qos_rv qres_set_weight	(	qres_sid_t	sid,
		unsigned int	weight
	)

Set scheduling weight (i.e., used by shrub).

Definition at line 343 of file qres_lib.c.

References check_open(), IOCTL_OP_SET_WEIGHT, qos_chk_rv, qos_int_rv, qos_log_debug, QOS_OK, qos_strerror(), qres_fd, qres_weight_iparams_t::server_id, and qres_weight_iparams_t::weight.

Referenced by main().