SchedCtl(), SchedCtl_r()

Контроль планировщика адаптивного квотирования ресурсов

Прототип:

#include <sys/sched_aps.h>
#include <sys/neutrino.h>
int SchedCtl( int cmd,
void *data,
int length );
int SchedCtl_r( int cmd,
void *data,
int length );

Аргументы:

cmd
The control command that you want to execute; one of:
data
A pointer to the specific data structure for the command.
length
The size of the structure that data points to.

Библиотека:

libc

Описание:

The SchedCtl() and SchedCtl_r() kernel calls control the adaptive partitioning scheduler.

This scheduler is optional and is present only if you add [module=aps] to your OS image's buildfile.

Данные функции идентичны за исключением способа возврата ошибок.


Note: You must initialize all of the fields—including reserved ones—in the structures you pass as the data argument, by calling (for example) memset(). You can also use the APS_INIT_DATA() macro:

APS_INIT_DATA( &data );


SCHED_APS_QUERY_PARMS

This command fills in a sched_aps_info structure that describes the overall parameters of the adaptive partitioning scheduler.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_QUERY_PARMS command:

EOK
Успешное завершение.
EACCES
The calling thread doesn't meet the security options set (see SCHED_APS_ADD_SECURITY). Usually this means you must be root.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_SET_PARMS

The command sets the parameters for the overall behavior of the adaptive partitioning scheduler. The data argument must be a pointer to a sched_aps_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_SET_PARMS command:

EOK
Успешное завершение.
EACCES
SCHED_APS_SEC_PARTITIONS_LOCKED is set, or SCHED_APS_SEC_ROOT0_OVERALL is set and you aren't running as root in the System partition. For more information, see SCHED_APS_SEC_*.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_CREATE_PARTITION

This command creates a new partition which is considered to be a child of the partition that's calling SchedCtl(). The system automatically creates a partition called System (the value of APS_SYSTEM_PARTITION_NAME) with an ID of 0.

The data argument for this command must be a pointer to a sched_aps_create_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_CREATE_PARTITION command:

EOK
Успешное завершение.
EACCES
SCHED_APS_SEC_PARTITIONS_LOCKED is set, or any of these security conditions are set and not satisfied: For more information, see sched_aps_security_parms structure.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EDQUOT
The parent partition doesn't have enough budget.
EEXIST
Another partition is already using the given name.
EINVAL
The size of the parameter block doesn't match the size of the expected structure, the partition name is badly formed, or the budget is out of range.
ENAMETOOLONG
The partition name is longer than APS_PARTITION_NAME_LENGTH characters.
ENOSPC
The maximum number of partitions already exist.
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_QUERY_PARTITION

This command gets information about a given partition. The data argument for this command must be a pointer to a sched_aps_partition_info structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_QUERY_PARTITION command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_LOOKUP

This command finds the partition ID for a given partition name. The data argument for this command must be a sched_aps_lookup_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_LOOKUP command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The name wasn't found.

SCHED_APS_JOIN_PARTITION

This command makes the thread specified by the given process and thread IDs becomes a member of the specified partition. This partition also becomes the thread's new home partition, i.e. where it returns after partition inheritance. The data argument for this command must be a pointer to a sched_aps_join_parms.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_JOIN_PARTITION command:

EOK
Успешное завершение.
EACCES
The following security options are set but not satisfied: For more information, see sched_aps_security_parms structure.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure, or the partition with the given ID doesn't exist.
ENOSYS
The adaptive partitioning scheduler isn't installed.
ESRCH
The pid and tid are invalid.

SCHED_APS_MODIFY_PARTITION

This command changes the parameters of an existing partition. If the new budget's percent value is different from the current, the difference is either taken from, or returned to, the parent partition's budget. The critical time parameter affects only the chosen partition, not its parent. To change just one of new budget or new critical time, set the other to -1.


Note:
  • You can't use this command to modify the System partition's budget. To increase the size of the System partition, reduce the budget of one of its child partitions.

  • Reducing the size of a partition may cause it not to run for the time of an averaging window, as you may have caused it to become temporarily over-budget. However, reducing the critical time doesn't trigger the declaration of bankruptcy.

The data argument for this command must be a pointer to a sched_aps_modify_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_MODIFY_PARTITION command:

EOK
Успешное завершение.
EACCES
SCHED_APS_SEC_PARTITIONS_LOCKED is set, or the following security options are set and not satisfied: For more information, see sched_aps_security_parms structure.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure, or the partition with the given ID doesn't exist.
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_PARTITION_STATS

This command returns instantaneous values of the CPU time-accounting variables for a set of partitions. It can fill in data for more than one partition. If the length argument to SchedCtl() indicates that you've passed the function an array of sched_aps_partition_stats structures, SchedCtl() fills each element with statistics for a different partition, starting with the partition specified by the id field.


Note: To get an accurate picture for the the whole machine it's important to read data for all partitions in one call, since sequential calls to SCHED_APS_PARTITION_STATS may come from separate averaging windows.

To determine the number of partitions, use the SCHED_APS_OVERALL_STATS command.


The command overwrites the id field with the partition number for which data is being returned. It stores -1 into the id field of unused elements. To convert times in cycles into milliseconds, divide them by the cycles_per_ms obtained with an SCHED_APS_QUERY_PARMS command.

The data argument for this command must be a pointer to a sched_aps_partition_stats structure, or an array of these structures.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_PARTITION_STATS command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block isn't a multiple of size( sched_aps_partition_stats ).
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_OVERALL_STATS

This command returns instantaneous values of overall CPU-usage variables and other dynamic scheduler states. The data argument for this command must be a pointer to a sched_aps_overall_stats structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_OVERALL_STATS command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_MARK_CRITICAL

This command sets one thread in your process to run as a critical thread whenever it runs. Use a thread ID of zero to set the calling thread to be critical. The data argument for this command must be a pointer to a sched_aps_mark_crit_parms structure.


Note: In general, it's more useful to send a critical struct sigevent to a thread to make it run as a critical thread.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_MARK_CRITICAL command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.
ESRCH
The specified thread wasn't found.

SCHED_APS_CLEAR_CRITICAL

This command clears the “always run as critical” state set by the SCHED_APS_CLEAR_CRITICAL command. Then the thread will run as critical only when it inherits that state from another thread (on receipt of a message). The data argument for this command must be a pointer to a sched_aps_clear_crit_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_CLEAR_CRITICAL command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.
ESRCH
The specified thread wasn't found.

SCHED_APS_QUERY_THREAD

This command determines the partition for the given thread and indicates whether or not the thread in your process is marked to run as critical. Use a thread ID of zero to indicate the calling thread. The data argument for this command must be a pointer to a sched_aps_query_thread_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_QUERY_THREAD command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.
ESRCH
The specified thread wasn't found.

SCHED_APS_ATTACH_EVENTS

This command defines struct sigevent that the scheduler will return to the calling thread when the scheduler detects that a given partition has become bankrupt, or the whole system has become overloaded.


Note: Overload notification isn't implemented in this release.

Calling SCHED_APS_ATTACH_EVENTS arms the notification once. After you receive the notification, you must call SCHED_APS_ATTACH_EVENTS again to receive a subsequent notification. This is to ensure that the system doesn't send you notifications faster than you can handle them. The pinfo_flags field of the sched_aps_partition_stats structure structure (see the SCHED_APS_PARTITION_STATS command) indicates if these events are armed.


Note: You can register only one pair of struct sigevent (bankruptcy and overload) per partition, and the notifications must go to the same thread. The thread notified is the calling thread. Attaching events a second time overwrites the first. Passing NULL pointers means “no changes in notification.” To turn off notification, use SIGEV_NONE_INIT() to set the appropriate struct sigevent to SIGEV_NONE.

If you want to configure additional actions for the system to perform on bankruptcy, see SCHED_APS_BNKR_*. The data argument for this command must be a pointer to a sched_aps_events_parm structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_ATTACH_EVENTS command:

EOK
Успешное завершение.
EACCES
You don't have the right to modify the partition, i.e the following security modes are set and not satisfied: For more information, see sched_aps_security_parms structure.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.
ESRCH
The specified thread wasn't found.

SCHED_APS_ADD_SECURITY

This command sets security options. A bit that's set turns the corresponding security option on. Successive calls add to the existing set of security options. Security options can only be cleared by a restart.


Note: You must be root running in the System partition to use this command, even if all security options are off.

The data argument for this command must be a pointer to a sched_aps_security_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_ADD_SECURITY command:

EOK
Успешное завершение.
EACCES
The calling thread doesn't meet the security options set (see SCHED_APS_ADD_SECURITY). Usually this means you must be root.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.

SCHED_APS_QUERY_PROCESS

This command returns the partition of the given process. The partition of a process is billed while one of the process's threads handles a pulse. The individual threads in a process may all be in different partitions from the process. The data argument for this command must be a pointer to a sched_aps_query_process_parms structure.

Errors:

SchedCtl() and SchedCtl_r() indicate the following errors for the SCHED_APS_QUERY_PROCESS command:

EOK
Успешное завершение.
EDOM
A reserved field isn't zero. You might not have used APS_INIT_DATA() to initialize the data parameter.
EINVAL
The size of the parameter block doesn't match the size of the expected structure.
ENOSYS
The adaptive partitioning scheduler isn't installed.
ESRCH
The process wasn't found.

Состояния блокировки:

This call doesn't block.

Возвращаемое значение:

SchedCtl()
EOK if the call succeeds. If an error occurs, SchedCtl() returns -1 and sets errno.
SchedCtl_r()
EOK if the call succeeds. This function doesn't set errno. If an error occurs, SchedCtl_r() returns the negative of an error value.

Коды ошибок:

For a list of error codes, see the description of each command.

Примеры:

sched_aps_partition_info part_info;
/* You need to initialize the parameter block. */
APS_INIT_DATA( &part_info );
/* Set the input members of the parameter block. */
part_info.id = 2;
/* Invoke SchedCtl to query the partition. */
ret = SchedCtl( SCHED_APS_QUERY_PARTITION, &part_info, sizeof( part_info ) );
if ( EOK != ret )
some_kind_of_error_handler();
/* Use output field */
printf( "The budget is %d per cent.\n", part_info.budget_percent );

Классификация:

ЗОСРВ «Нейтрино»

Точка остановки потока
Нет
Обработчик прерываний
Нет
Обработчик сигналов
Да
В потоке
Да

Тематические ссылки:

sched_aps_info structure, sched_aps_parms structure, sched_aps_create_parms structure, sched_aps_partition_info structure, sched_aps_lookup_parms structure, sched_aps_join_parms structure, sched_aps_modify_parms structure, sched_aps_partition_stats structure, sched_aps_overall_stats structure, sched_aps_mark_crit_parms structure, sched_aps_clear_crit_parms structure, sched_aps_query_thread_parms structure, sched_aps_events_parm structure, sched_aps_security_parms structure, sched_aps_query_process_parms structure, SchedGet(), SchedInfo(), SchedSet(), SchedYield(), struct sigevent

aps в Справочнике по Утилитам




Предыдущий раздел: Описание API системной библиотеки