CGPOLL(8)

NAME
cgpoll - wait for a cgroup to go vacant, or for it to freeze

SYNOPSIS
cgpoll [-U | -D] [-f | -F] [-n] [-t timeout-ms] cgroup [prog...]

DESCRIPTION
cgpoll listens for changes in the number of processes inside of the Linux kernel control group cgroup by placing an inotify(7) watch on its cgroup.events file. If absolute, cgroup is interpreted relative to /sys/fs/cgroup; if relative, it is interpreted relative to the current process's cgroup.

If no options are given, or if the -D option is given, cgpoll will wait until there are no processes left in cgroup. If the -U option is given, cgpoll will instead wait until there is at least one process in cgroup.

If the -f option is given, cgpoll will wait for cgroup to report that it is frozen. If the -F option is given, it will wait for cgroup to report that it is unfrozen (by default, events relating to freezing are ignored).

If the -t option is given a nonzero value, cgpoll will wait for up to timeout-ms milliseconds. if not, it will wait indefinitely.

When one of the expected events (related to either population or freezing status) happens, either prog... is executed, or, if it was not specified, cgpoll exits successfully. If timeout-ms is reached without -U or -D being satisfied, cgpoll will exit unsuccessfully.

The behavior described above can be inverted with the -n option; if it is given, a timeout will cause a successful exit or a exec(3), and satisfaction of the condition causes an unsuccessful exit.

EXIT STATUS

•   If cgpoll finds any user errors, such as invalid command line options, it exits 100.

•   If cgpoll encounters an operating system error, including cgroup being nonexistent, it exits 111.

•   If the -U or -D conditions are satisfied without the -n option , or timeout-ms is reached with the -n option cgpoll will either exec(3) prog... if it is given, or exit 0.

•   If prog... fails to execute, cgpoll exits 127 (if it was not found) or 126 (if another error occured).

•   Otherwise, cgpoll will exit 1.

EXAMPLES

    srv_cg=/service/absentparentd
    cgpoll -t 3000 -nD "$srv_cg" \
      chcgs -xo cgroup.kill=1 "$srv_cg"
    rmdir "/sys/fs/cgroup/$srv_cg"

Kill every process in cgroup ‘/service/absentparentd’, if there are still processes in it after 3 seconds, and remove the control group. This could be used as the finish script of a runsv(8) or s6-service-directory(7) to emulate systemd.kill(5)' s ‘KillMode=mixed’ with a ‘TimeoutStopSec’ of 3.

    srv_cg=/service/lotsofprocesses
    chcgs -xo cgroup.freeze=1 "$srv_cg"
    cgpoll -f "$srv_cg"
    cgcat "$srv_cg" cgroup.procs xargs kill -TERM --
    cgcat "$srv_cg" cgroup.procs xargs kill -CONT --
    chcgs -xo cgroup.freeze=0 "$srv_cg"
    cgpoll -t 3000 -nD "$srv_cg"
      chcgs -xo cgroup.kill=1 "$srv_cg"
    rmdir "/sys/fs/cgroup/$srv_cg"

A reimplementation of cgslay(1): https://list.skarnet.org/lists/supervision/att-3320/cgslay.c, that attempts to gracefully kill every process in the cgroup before using the file that atomically kills everything.

SEE ALSO
cgroup(7), chcgs(8), cgcat(8),

AUTHORS
Carlos Pezotte <carana2099@gmail.com>

CAVEATS

•   Most service managers enforce time limits for prep-work/cleanup scripts. In these contexts, always use a suitable value of timeout-ms.

•   cgpoll only supports the version 2 cgroups(7) interface.