sched_setattr(2)

NAZWA
sched_setattr, sched_getattr - ustawia i pobiera algorytm i parametry szeregowania

BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)

SKŁADNIA
#include <sched.h>            /* Definicja stałych SCHED_* */
#include <sys/syscall.h>      /* Definicja stałych SYS_* */
#include <unistd.h>

int syscall(SYS_sched_setattr, pid_t pid, struct sched_attr *attr,
            unsigned int flags);
int syscall(SYS_sched_getattr, pid_t pid, struct sched_attr *attr,
            unsigned int size, unsigned int flags);

Uwaga: glibc nie udostępnia opakowania dla tych wywołań systemowych, co wymusza użycie syscall(2).

OPIS

  sched_setattr()
Wywołanie systemowe sched_setattr() ustawia algorytm szeregowania i powiązane atrybuty wątku, którego identyfikator podano w pid. Jeśli pid równa się zero, ustawi algorytm i parametry szeregowania wątku wywołującego.

Obecnie, Linux obsługuje następujące „zwykłe” (tj. nie czasu rzeczywistego) algorytmy szeregowania zadań, które można podać jako wartości policy:

SCHED_OTHER
    standardowy algorytm dzielenia czasu za pomocą szeregowania rotacyjnego;

SCHED_BATCH
    do wykonywania procesów w stylu „wsadowym” oraz

SCHED_IDLE
    do uruchamiania zadań tła, o bardzo niskim priorytecie.

Obsługiwane są również różne algorytmy „czasu rzeczywistego”, nadające się do specjalnych aplikacji, gdzie krytyczna jest precyzyjna kontrola nad sposobem, w jaki działające wątki są wybierane do wykonania. Aby dowiedzieć się więcej o zasadach regulujących okoliczności, w jakich wątki procesu mogą używać tych algorytmów, należy zapoznać się z podręcznikiem sched(7). Algorytmy czasu rzeczywistego, jakie można określić w policy to:

SCHED_FIFO
    algorytm: pierwszy na wejściu, pierwszy na wyjściu oraz

SCHED_RR
    szeregowanie rotacyjne (karuzelowe).

Linux zapewnia również poniższy algorytm:

SCHED_DEADLINE
    szeregowanie sporadyczne z budżetem czasu; więcej szczegółów w podręczniku sched(7).

Argument attr jest wskaźnikiem do struktury definiującej nowy algorytm szeregowania, wraz z atrybutami, danego wątku. Struktura ma postać:

    struct sched_attr {
        u32 size;              /* Rozmiar tej struktury */
        u32 sched_policy;      /* Algorytm (SCHED_*) */
        u64 sched_flags;       /* Znaczniki */
        s32 sched_nice;        /* Wartość nice (SCHED_OTHER,
                                  SCHED_BATCH) */
        u32 sched_priority;    /* Priorytet statyczny (SCHED_FIFO,
                                  SCHED_RR) */
        /* W SCHED_DEADLINE */
        u64 sched_runtime;
        u64 sched_deadline;
        u64 sched_period;

        /* Wskazówki dot. użycia */
        u32 sched_util_min;
        u32 sched_util_max;

Polami struktury sched_attr są:

size
    Pole powinno być ustawione na rozmiar struktury w bajtach, jak w sizeof(struct sched_attr). Jeśli zapewniona struktura jest mniejsza niż struktura jądra, dodatkowe pola są przyjmowane jako '0'. Jeśli zapewniona struktura jest większa niż struktura jądra, jądro weryfikuje, czy wszystkie dodatkowe pola wynoszą 0; jeśli tak nie jest, sched_setattr() zawodzi z błędem E2BIG i aktualizuje size tak, aby zawierało rozmiar struktury jądra.

    Powyższe zachowanie dotyczące przypadku, gdy rozmiar struktury sched_attr z przestrzeni użytkownika nie pasuje do rozmiaru struktury jądra, pozwala na rozszerzenie interfejsu w przyszłości. Nieprawidłowe aplikacje przekazujące nadmiarowe struktury będą wciąż działać w przyszłości, jeśli rozmiar struktury sched_attr jądra ulegnie zwiększeniu. W przyszłości, może również pozwolić aplikacjom, które wiedzą o większej strukturze sched_attr w przestrzeni użytkownika na określenie, czy działają na starszym jądrze, nieobsługującym większej struktury.

sched_policy
    Pole określa algorytm szeregowania, będący jedną z wartości SCHED_* podanych wyżej.

sched_flags
    Pole zawiera jeden lub więcej zsumowanych (OR) poniższych znaczników, służących do kontroli zachowania szeregowania zadań:

    SCHED_FLAG_RESET_ON_FORK
        Potomkowie utworzeni przez fork(2) nie odziedziczą uprzywilejowanych algorytmów szeregowania. Więcej szczegółów w podręczniku sched(7).

    SCHED_FLAG_RECLAIM (od Linuksa 4.13)
        Znacznik pozwala wątkowi SCHED_DEADLINE na odzyskanie przepustowości nieużywanej przez inne wątki czasu rzeczywistego.

    SCHED_FLAG_DL_OVERRUN (od Linuksa 4.16)
        Znacznik pozwala na informowanie aplikacji o przekroczeniu czasu działania w wątkach SCHED_DEADLINE. Może być ono spowodowane (na przykład) przez zbyt zgrubne liczenie czasu lub nieprawidłowe przypisanie parametrów. Informowanie zachodzi za pośrednictwem sygnału SIGXCPU, wysyłanego przy każdym przekroczeniu czasu działania.

        Sygnał SIGXCPU jest sygnałem skierowanych do procesu (zob. signal(7)), a nie skierowanym do wątku. Należy to prawdopodobnie traktować jako usterkę. Z jednej strony, sched_setattr() jest używane do ustawienia atrybutu przynależnemu wątkowi. Z drugiej strony, jeśli sygnał skierowany do procesu jest dostarczony do wątku wewnątrz procesu, innego niż ten, który przekroczył czas działania, aplikacja nie ma sposobu, aby zidentyfikować wątek winowajcę.

    SCHED_FLAG_UTIL_CLAMP_MIN
    SCHED_FLAG_UTIL_CLAMP_MAX (oba od Linuksa 5.3)
        Znaczniki wskazują, że obecne jest, odpowiednio, pole sched_util_min lub sched_util_max, reprezentując oczekiwane minimalne i maksymalne użycie przez wątek.

        Atrybuty użycia zakreślają dyspozytorowi granice, pomiędzy którymi powinien szeregować wątek, potencjalnie pomagając podejmować decyzje dotyczące umieszczenia zadania i częstotliwości jego wyboru.

sched_nice
    Pole określa wartość nice do ustawienia przy przekazywaniu algorytmu szeregowania sched_policy SCHED_OTHER lub SCHED_BATCH. Wartość nice jest liczbą z przedziału od -20 (wysoki priorytet) do +19 (niski priorytet); zob. sched(7).

sched_priority
    Pole określa statyczny priorytet do ustawienia przy przekazywaniu algorytmu szeregowania sched_policy SCHED_FIFO lub SCHED_RR. Dozwolony przedział priorytetów w tych algorytmach można sprawdzić za pomocą sched_get_priority_min(2) i sched_get_priority_max(2). Przy innych algorytmach, to pole musi być ustawione na 0.

sched_runtime
    Pole określa parametr „Czas Działania” przy szeregowaniu z budżetem czasu. Wartość jest wyrażana w nanosekundach. Pole to, razem z kolejnymi dwoma, jest używane tylko przy algorytmie SCHED_DEADLINE; szerszy opis w podręczniku sched(7).

sched_deadline
    Pole określa parametr „Limit” przy szeregowaniu z budżetem czasu. Wartość jest wyrażana w nanosekundach.

sched_period
    Pole określa parametr „Okres” przy szeregowaniu z budżetem czasu. Wartość jest wyrażana w nanosekundach.

sched_util_min
sched_util_max (oba od Linuksa 5.3)
    Pola określają, odpowiednio, minimalne i maksymalne oczekiwane użycie. Są ignorowane, chyba że w sched_flags ustawiono, odpowiednio, SCHED_FLAG_UTIL_CLAMP_MIN lub SCHED_FLAG_UTIL_CLAMP_MAX .

    Użycie jest wartością z przedziału [0, 1024], reprezentującą procentowy czas procesora używany przez zadania działające przy maksymalnej częstotliwości na najmocniejszym procesorze w systemie. Jest to reprezentacja stałopozycyjna, gdzie 1024 odpowiada 100%, a 0 odpowiada 0%. Na przykład zadanie z 20% użyciem jest zadaniem działającym przez 2ms co każde 10ms przy maksymalnej częstotliwości i jest reprezentowane przez wartość użycia równą 0.2 * 1024 = 205.

    Zadanie o minimalnej wartości użycia większej od 0 ma większe prawdopodobieństwo uzyskania dostępu do procesora, którego możliwości są wystarczające do pomieszczenia podanej wartości. Zadanie o maksymalnej wartości użycia mniejszej od 1024 ma większe prawdopodobieństwo uzyskania dostępu do procesora, którego możliwości są nie większe niż podana wartość.

    Granice użycia zadania można zresetować ustawiając dane pole na UINT32_MAX (od Linuksa 5.11).

Argument flags pozwala na przyszłe rozszerzenia interfejsu; w bieżącej implementacji musi być określony jako 0.

  sched_getattr()
Wywołanie systemowe sched_getattr() pobiera algorytm szeregowania, wraz z powiązanymi atrybutami, dla wątku, którego identyfikator podano w pid. Jeśli pid jest równe zero, pobiera algorytm szeregowania, wraz z powiązanymi atrybutami, wątku wywołującego.

Argument size należy ustawić na rozmiar struktury sched_attr znany przestrzeni użytkownika. Wartość musi być co najmniej tak duża, jak rozmiar pierwotnie ogłoszonej struktury sched_attr (por. opis E2BIG w rozdziale BŁĘDY - przyp. tłum.), w innym przypadku wywołanie zawiedzie z błędem EINVAL.

Pobrane atrybuty szeregowania są umieszczane w polach struktury sched_attr, na którą wskazuje attr. Jądro ustawi attr.size na rozmiar jego struktury sched_attr.

Jeśli bufor attr zapewniony przez wywołującego jest większy niż struktura jądra sched_attr, dodatkowe bajty w strukturze w przestrzeni użytkownika nie są modyfikowane. Jeśli struktura zapewniona przez wywołującego jest mniejsza od struktury jądra sched_attr, jądro po cichu niż zwróci wartości, które znalazłyby się poza zapewnioną przestrzenią. Podobnie jak przy sched_setattr(), takie zachowanie pozwala na przyszłe rozszerzanie interfejsu.

Argument flags pozwala na przyszłe rozszerzenia interfejsu; w bieżącej implementacji musi być określony jako 0.

WARTOŚĆ ZWRACANA
W przypadku powodzenia, sched_setattr() i sched_getattr() zwracają 0. W razie wystąpienia błędu zwracają -1 i ustawiają errno wskazując błąd.

BŁĘDY
sched_getattr() oraz sched_setattr() mogą zawieść z następujących powodów:

EINVAL
    attr wynosi NULL; albo pid jest ujemne; albo flags nie jest zerem.

ESRCH
    Nie znaleziono wątku o identyfikatorze równym pid.

Dodatkowo, sched_getattr() może zawieść z następujących powodów:

E2BIG
    Bufor określony przez size i attr jest zbyt mały.

EINVAL
    size jest nieprawidłowy; tj. jest mniejszy niż pierwotna wersja struktury sched_attr (48 bajtów) lub jest większy od systemowego rozmiaru strony.

Dodatkowo, sched_setattr() może zawieść z następujących powodów:

E2BIG
    Bufor określony przez size i attr jest większy niż struktura jądra, a jeden lub więcej nadmiarowych bajtów jest niezerowy.

EBUSY
    Błąd testu przyjęcia SCHED_DEADLINE, zob. sched(7).

EINVAL
    attr.sched_policy nie jest jednym z rozpoznawanych algorytmów szeregowania.

EINVAL
    attr.sched_flags zawiera znacznik inny niż SCHED_FLAG_RESET_ON_FORK.

EINVAL
    attr.sched_priority jest nieprawidłowy.

EINVAL
    attr.sched_policy wynosi SCHED_DEADLINE, a parametry szeregowania z budżetem czasu w attr są nieprawidłowe.

EINVAL
    attr.sched_flags zawiera SCHED_FLAG_UTIL_CLAMP_MIN lub SCHED_FLAG_UTIL_CLAMP_MAX, a attr.sched_util_min lub attr.sched_util_max są spoza zakresu.

EOPNOTSUPP
    Podano SCHED_FLAG_UTIL_CLAMP, lecz jądro zbudowano bez obsługi CONFIG_UCLAMP_TASK.

EPERM
    Wywołujący nie ma odpowiednich przywilejów.

EPERM
    Maska koligacji procesora dla wątku określonego przez pid nie obejmuje wszystkich procesorów w systemie (zob. sched_setaffinity(2)).

STANDARDY
Linux.

HISTORIA
Linux 3.14.

UWAGI
glibc nie zapewnia opakowań tych wywołań systemowych; należy je wywołać za pomocą syscall(2).

sched_setattr() zapewnia nadzbiór funkcjonalności sched_setscheduler(2), sched_setparam(2), nice(2) i (poza możliwością ustawienia priorytetu wszystkich procesów należących do podanego użytkownika i wszystkich procesów w podanej grupie) setpriority(2). Analogicznie, sched_getattr() zapewnia nadzbiór funkcjonalności sched_getscheduler(2), sched_getparam(2) i (częściowo) getpriority(2).

USTERKI
W wersjach Linuksa do 3.15, sched_setattr() zawodził z błędem EFAULT zamiast E2BIG, w przypadku opisanym w rozdziale BŁĘDY.

Do Linuksa 5.3, sched_getattr() zawodził z błędem EFBIG, jeśli struktura jądra sched_attr była większa od rozmiaru size przekazanego z przestrzeni użytkownika.

ZOBACZ TAKŻE
chrt(1), nice(2), sched_get_priority_max(2), sched_get_priority_min(2), sched_getaffinity(2), sched_getparam(2), sched_getscheduler(2), sched_rr_get_interval(2), sched_setaffinity(2), sched_setparam(2), sched_setscheduler(2), sched_yield(2), setpriority(2), pthread_getschedparam(3), pthread_setschedparam(3), pthread_setschedprio(3), capabilities(7), cpuset(7), sched(7)

TŁUMACZENIE
Tłumaczenie niniejszej strony podręcznika: Michał Kułach <michal.kulach@gmail.com>

Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 (https://www.gnu.org/licenses/gpl-3.0.html) lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-list@lists.sourceforge.net.