.TH "workload" 1 "07 April 1996" .SH "NAME" Synthetic workload generator. .SH "SYNOPSIS" .nf workload [] .fi .sp 1 .SH "DESCRIPTION" .PP This is a driver to generate a workload with specified parameters, where the workload consists of user commands to be executed. The workload may be 'do this 1000 times in a row' or 'do 100 of these all at the same time' or more complex constructions. .PP \fIworkload\fP reads a single \fIjob\fP specification from the specified file, or standard in if none is specified. This job (possibly quite complex) is then executed. .SH "WORKLOAD SPECIFICATION LANGUAGE" .PP The language read by \fIworkload\fP allows for comments, any text following an octothorpe (# character) on a line is discarded. The remainder is parsed, ignoring newlines and other whitespace -- except as needed to separate keywords from one another, into a job description. .PP The notion of a \fIjob\fP is defined recursively. The simplest job is .nf .sp 1 .RS 5 command "" .RE .sp 1 .fi which simply executes the command specified in the string. The string is tokenized and execvp()'d. No filename globbing or metacharacter handling is done. There are also complex job specifiers for doing a set of jobs in sequence, in parallel, or in a (deterministic) pseudo random order. .PP A set of of jobs can be carried out in sequence by using the \fIsequential\fP keyword. The first form carries out each of the specified jobs, in the order specified. Each job must conclude before the next one is started. The second form does the same thing a specified number of times, as specified by the repeat count. .nf .sp 1 .RS 5 sequential { <1 or more job specifiers> } sequential { <1 or more job specifiers> } .RE .sp 1 .fi The \fIparallel\fP keyword has exactly the same syntax as the \fIsequential\fP keyword, but the semantics are different. Rather than waiting for each job to conclude, all are started in the same order as with the sequential form, but as fast as possible. The \fIparallel\fP construct then waits for all of the jobs to complete before it is itself complete. .PP The last job type is \fIrandom\fP. This also has two forms: .nf .sp 1 .RS 5 random { <1 or more job specifiers> } random pid { <1 or more job specifiers> } .RE .sp 1 .fi This is intermediate between the \fIsequential\fP and the \fIparallel\fP constructs. The repeat count is not optional, and there are three additional arguments which determine the pseudo-random intervals between job starts. The jobs are started as in the two other constructs, except that the interval between job starts is determined by successive calls to random(3). The output of random(3) is used to select a uniformly distributed number between and to start the next job in sequence. If specified as a number, the value is used to as the argument to srandom(3), to provide repeatable results. If specified as the string "pid", the process ID is used to seed the random number generator. Since each instance of job is handled by a separate process, this guarantees a variety of seeds, at the expense of strict repeatability. .PP When all the jobs have been started, \fIworkload\fP waits for all to complete before the job is complete. .SH "EXAMPLES" .nf .sp 1 .RS 5 sequential 1 { command "ls -l" } .RE .sp 1 .fi will cause the command 'ls -l' to be executed once. .nf .sp 1 .RS 5 parallel 5 { command "ls -l" } .RE .sp 1 .fi will launch 5 copies of 'ls -l' at once, and wait for them all to terminate. .nf .sp 1 .RS 5 sequential 3 { parallel 5 { command "ls -l" } } .RE .sp 1 .fi will run 5 copies of 'ls -l' in parallel, wait for them to all terminate, and then do it again 2 more times. Finally: .nf .sp 1 .RS 5 sequential 3 { random 5 42 1-3 { command "test-script" } } .RE .sp 1 .fi Will start 5 copies of 'test-script' at pseudo-random intervals between 1 and 3 seconds (srandom() used to seed the standard library random number generator with 42), and then wait for them all to terminate. Then it'll do it twice more, for a total of 3 sequential instances of the pseudo-random job. .PP Naturally, job specifications can be nested more deeply (indeed, as deeply as you like). .PP .SH "ENVIRONMENT" \fIworkload\fP does not use any environment variables. .SH "FILES" \fIworkload\fP does not use any specific files. .SH "BUGS" \fIworkload\fP does not have any known bugs. The behavior of random jobs is perhaps not as good as it could be, but the author cannot think of better semantics. .PP When using a random job specifier with a specified seed value, nested inside a parallel specifier with a repeat count, the results may be less random than hoped. This is because each of the repeated parallel instances of the random job will be seeding their random number generator identically, and therefore each will be starting their jobs at the same pseudo-random time. If strict repeatability is not required, use the "pid" form of the seed. If strict repeatability is required, not not use a repeat count with the parallel specifier, but rather replicate the random job multiple times, and specify different seeds for each copy. .PP For example .nf .sp 1 .RS 5 parallel 3 { random 1 42 10 20 { command "ls -l" } } .RE .sp 1 .fi will, at some pseudo-random time between 10 and 20 seconds, launch three instances of ls in parallel. Using, instead: .nf .sp 1 .RS 5 parallel 3 { random 1 pid 10 20 { command "ls -l" } } .RE .sp 1 .fi will start 3 parallel jobs, each of which will individually execute a copy of ls at some pseudo-random, not repeatable, time. Using: .nf .sp 1 .RS 5 parallel { random 1 42 10 20 { command "ls -l" } random 1 123 10 20 { command "ls -l" } random 1 555 10 20 { command "ls -l" } } .RE .sp 1 .fi will do the same thing, except in a repeatable fashion. .PP In addition, \fIworkload\fP adds overhead to any test configuration. It creates and destroys processes fairly promiscuously. It is therefore important to establish a baseline in any experiments. That is, one should first conduct a control experiment with \fIworkload\fP generating the synthetic workload in some standard context, then conduct the experiment again with whatever is to be tested inserted. By examining the deltas, hopefully one can gain useful information. .PP If the individual 'command' jobs are very short-lived or otherwise cheap, \fIworkload\fP may constitute so much of the total load that real data is lost in the noise. Use caution. Be a scientist. .SH "AUTHOR" Andrew Molitor, amolitor@network.com.