util: Introduce "subprogram_name" to identify subprocesses and threads.
[openvswitch] / lib / stress-unixctl.man
1 .SS "STRESS OPTION COMMANDS"
2 These command manage stress options, which allow developers testing
3 Open vSwitch to trigger behavior that otherwise would occur only in
4 corner cases.  Developers and testers can thereby more easily discover
5 bugs that would otherwise manifest only rarely or
6 nondeterministically.  Stress options may cause surprising behavior
7 even when they do not actually reveal bugs, so they should only be
8 enabled as part of testing Open vSwitch.
9 .
10 .IP "\fBstress/enable\fR"
11 .IQ "\fBstress/disable\fR"
12 All stress options are disabled by default.  Use \fBstress/enable\fR
13 to enable stress options and \fBstress/disable\fR to disable them.
14 .
15 .IP "\fBstress/list\fR"
16 Lists and describes the available stress options and their settings in
17 tabular form.  The columns in the table are:
18 .RS
19 .IP "NAME"
20 A single-word identifier for the option, used to identify stress
21 options to \fBstress/set\fR.
22 .
23 .IP "DESCRIPTION"
24 A description for a person unfamiliar with the detailed internals of
25 the code what behavior the option affects.
26 .
27 .IP "PERIOD"
28 Currently configured trigger period.  If the stress option is
29 disabled, this is \fBdisabled\fR.  Otherwise this is a number giving
30 the number of occurrences of the event between activations of the
31 stress option triggers.
32 .
33 .IP "MODE"
34 If the stress option is disabled, this is \fBn/a\fR.  Otherwise it is
35 \fBperiodic\fR if the stress option triggers after exactly the period,
36 or \fBrandom\fR if it triggers randomly but on average after the
37 number of occurrences specified by the period.
38 .
39 .IP "COUNTER"
40 If the stress option is disabled, this is \fBn/a\fR.  Otherwise it is
41 the number of occurrences of the event before the next time the stress
42 option triggers.
43 .
44 .IP "HITS"
45 The number of times that this stress option has triggered since this
46 program started.
47 .
48 .IP "RECOMMENDED"
49 A suggested period for a person unfamiliar with the internals.  It
50 should put reasonable stress on the system without crippling it.
51 .
52 .IP "MINIMUM"
53 .IQ "MAXIMUM"
54 Minimum and maximum values allowed for the period.
55 .
56 .IP "DEFAULT"
57 The default period, used when stress options have been enabled (with
58 \fBstress/enable\fR) but this particular stress option has not been
59 specifically configured (with \fBstress/set\fR).  It is \fBdisabled\fR
60 if the option is disabled by default.  It is nonzero for options that
61 can be left on at low levels without noticeable impact to the end user.
62 .RE
63 .
64 .IP "\fBstress/set \fIoption\fR \fIperiod\fR [\fBrandom\fR|\fBperiodic\fR]"
65 Sets the period at which stress \fIoption\fR triggers to
66 \fIperiod\fR.  A \fIperiod\fR of 0 disables \fIoption\fR.  Specify
67 \fBrandom\fR to make the option trigger randomly with an average
68 period of \fIperiod\fR, or \fBperiodic\fR to trigger exactly every
69 \fIperiod\fR events; the latter is the default.
70 .IP
71 If stress options have not been enabled with \fBstress/enable\fR, this
72 command has no effect.