Skip to content

Commit eb9bf22

Browse files
zacikpazacikpa
committed
docs: Update built-in function docstrings
The docs are now asciidoc with examples, ready to be included into the manual.
1 parent 9ebcff4 commit eb9bf22

25 files changed

+202
-67
lines changed

‎tuned/profiles/functions/function_assertion.py‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,17 @@
88

99
class assertion(base.Function):
1010
"""
11-
Assertion: compares argument 2 with argument 3. If they don't match
12-
it logs text from argument 1 and throws InvalidProfileException. This
13-
exception will abort profile loading.
11+
Compares the second argument and the third argument.
12+
If they _do not match_, the function logs the text from
13+
the first argument as an error and aborts profile loading.
14+
15+
====
16+
The following will log the error message `fatal error`
17+
and abort profile loading:
18+
----
19+
${f:assertion:fatal error:3:5}
20+
----
21+
====
1422
"""
1523
def __init__(self):
1624
# 3 arguments

‎tuned/profiles/functions/function_assertion_non_equal.py‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,16 @@
88

99
class assertion_non_equal(base.Function):
1010
"""
11-
Assertion non equal: compares argument 2 with argument 3. If they match
12-
it logs text from argument 1 and throws InvalidProfileException. This
13-
exception will abort profile loading.
11+
Compares the second argument and the third argument.
12+
If they _match_, the function logs the text from
13+
the first argument as an error and aborts profile loading.
14+
15+
====
16+
The following will pass without errors:
17+
----
18+
${f:assertion_non_equal:fatal error:3:5}
19+
----
20+
====
1421
"""
1522
def __init__(self):
1623
# 3 arguments

‎tuned/profiles/functions/function_calc_isolated_cores.py‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,16 @@
88

99
class calc_isolated_cores(base.Function):
1010
"""
11-
Calculates and returns isolated cores. The argument specifies how many
12-
cores per socket reserve for housekeeping. If not specified, 1 core
13-
per socket is reserved for housekeeping and the rest is isolated.
11+
Calculates and returns a list of isolated cores. The argument
12+
specifies how many cores per socket should be reserved for housekeeping.
13+
If not specified, a single core is reserved per socket and the rest is isolated.
14+
15+
====
16+
Reserve two cores per socket for housekeeping and return the list of remaining cores:
17+
----
18+
${f:calc_isolated_cores:2}
19+
----
20+
====
1421
"""
1522
def __init__(self):
1623
# max 1 argument

‎tuned/profiles/functions/function_check_net_queue_count.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55

66
class check_net_queue_count(base.Function):
77
"""
8-
Checks whether the user has specified a queue count for net devices. If
9-
not, return the number of housekeeping CPUs.
8+
Checks whether the first argument is a valid queue count for net devices.
9+
If yes, returns it, otherwise returns the number of housekeeping CPUs.
1010
"""
1111
def __init__(self):
1212
# 1 argument

‎tuned/profiles/functions/function_cpuinfo_check.py‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,17 @@
66

77
class cpuinfo_check(base.Function):
88
"""
9-
Checks regexes against /proc/cpuinfo. Accepts arguments in the
10-
following form: REGEX1, STR1, REGEX2, STR2, ...[, STR_FALLBACK]
11-
If REGEX1 matches something in /proc/cpuinfo it expands to STR1,
12-
if REGEX2 matches it expands to STR2. It stops on the first match,
13-
i.e. if REGEX1 matches, no more regexes are processed. If none
14-
regex matches it expands to STR_FALLBACK. If there is no fallback,
15-
it expands to empty string.
9+
Checks regexes against the content of `/proc/cpuinfo`.
10+
11+
Accepts arguments in the form `REGEX1, STR1, REGEX2, STR2, ...[, STR_FALLBACK]`.
12+
13+
If `REGEX1` has a match in `/proc/cpuinfo`, it returns `STR1`.
14+
15+
If `REGEX2` has a match, it returns `STR2`.
16+
17+
The function stops on the first match, i.e., if `REGEX1` has a match,
18+
no more regexes are processed. If no regex has a match, `STR_FALLBACK`
19+
is returned. If there is no fallback value, it returns an empty string.
1620
"""
1721
def __init__(self):
1822
# unlimited number of arguments, min 2 arguments

‎tuned/profiles/functions/function_cpulist2devs.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,14 @@
55

66
class cpulist2devs(base.Function):
77
"""
8-
Conversion function: converts CPU list to device strings
8+
Converts a CPU list into a comma-separated list of device names.
9+
10+
====
11+
The following will return `cpu1,cpu2,cpu3,cpu5`:
12+
----
13+
${f:cpulist2devs:1-3,5}
14+
----
15+
====
916
"""
1017
def __init__(self):
1118
# arbitrary number of arguments

‎tuned/profiles/functions/function_cpulist2hex.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,14 @@
77

88
class cpulist2hex(base.Function):
99
"""
10-
Conversion function: converts CPU list to hexadecimal CPU mask
10+
Converts a CPU list into a hexadecimal CPU mask.
11+
12+
====
13+
The following will return `00000007`.
14+
----
15+
${f:cpulist2hex:0-3}
16+
----
17+
====
1118
"""
1219
def __init__(self):
1320
# arbitrary number of arguments

‎tuned/profiles/functions/function_cpulist2hex_invert.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,15 @@
77

88
class cpulist2hex_invert(base.Function):
99
"""
10-
Converts CPU list to hexadecimal CPU mask and inverts it
10+
Converts a CPU list into a hexadecimal CPU mask and inverts it.
11+
12+
====
13+
On a system with 4 CPUs numbered from 0 to 3, the following will
14+
return `00000002`, because only CPU1 is in the complement.
15+
----
16+
${f:cpulist2hex_invert:0,2,3}
17+
----
18+
====
1119
"""
1220
def __init__(self):
1321
# arbitrary number of arguments

‎tuned/profiles/functions/function_cpulist_invert.py‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,15 @@
77

88
class cpulist_invert(base.Function):
99
"""
10-
Inverts list of CPUs (makes its complement). For the complement it
11-
gets number of online CPUs from the /sys/devices/system/cpu/online,
12-
e.g. system with 4 CPUs (0-3), the inversion of list "0,2,3" will be
13-
"1"
10+
Inverts a CPU list, i.e., returns its complement. The complement is
11+
computed from the list of online CPUs in `/sys/devices/system/cpu/online`.
12+
13+
====
14+
On a system with 4 CPUs numbered from 0 to 3, the following will return `1`.
15+
----
16+
${f:cpulist_invert:0,2,3}
17+
----
18+
====
1419
"""
1520
def __init__(self):
1621
# arbitrary number of arguments

‎tuned/profiles/functions/function_cpulist_online.py‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,15 @@
77

88
class cpulist_online(base.Function):
99
"""
10-
Checks whether CPUs from list are online, returns list containing
11-
only online CPUs
10+
Returns a CPU list containing the online CPUs from the given CPU list.
11+
12+
====
13+
On a system with 8 CPUs where the first 4 CPUs (0 to 3) are offline,
14+
the following returns `4-6`:
15+
----
16+
${f:cpulist_online:0-6}
17+
----
18+
====
1219
"""
1320
def __init__(self):
1421
# arbitrary number of arguments

0 commit comments

Comments
 (0)