job(3tnm)

NAME

Tnm::job - Invoke Tcl procedures at regular intervals.

DESCRIPTION

The Tnm::job command provides a convenient mechanism to invoke Tcl procedures at regular intervals. Jobs are activated from the Tcl event loop. It is therefore necessary that the Tcl event loop has been entered in order to execute jobs. Jobs are never interrupted due to the event-driven nature of Tcl. This means that long computations or blocking Tcl or Tnm commands can change the scheduling order noticeably.

Every job can have arbitrary attributes to store job specific state information between two invocations. These attributes help to avoid global variables in order to keep the Tcl name-space clean. Jobs can also have a set of tags which allows to group jobs and to relate jobs to other parts of an application.

The job scheduler itself relies heavily on the Tcl timer interface which itself depends on the system clock. Moving the system clock backwards can have the effect that jobs are not activated for the amount of time the system clock was moved backwards. Similarly, moving the system clock forward can have the effect that jobs are activated earlier for the amount of time the system clock was moved forward.

JOB COMMAND

The Tnm::job command allows to create new jobs and to wait for jobs to complete. The Tnm::job command can also be used to retrieve status information from the job scheduler.

Tnm::job create [option value ...]

The Tnm::job create command creates a new job object. The options can be used to configure the behaviour of the new job. See the configure command below for the details.

Tnm::job current

The Tnm::job current command returns the name of the currently running job. An empty string is returned if no job is running.

Tnm::job find [-status state] [-tags patternList]

The Tnm::job find command returns lists of job names. The list will contain all jobs known by the Tcl interpreter if no options are present. The -status option restricts the list to those jobs which are currently in the state state. The -tags option matches the tags associated with a job against the pattern contained in the patternList. Matching is done according to the rules defined for the Tcl string match command. Every pattern in the patternList must match at least one tag in the tag list.

Tnm::job schedule

The Tnm::job schedule command invokes the scheduler. This is usually done automatically from the event loop. This command may be used during long computations to invoke the scheduler explicitly. Note that this command can cause arbitrary side effects and should be used with care.

Tnm::job wait

The Tnm::job wait command blocks until all existing jobs in this interpreter have been finished. The command will wait infinitely if there is at least one job left. Events are processed while waiting for the jobs to finish, which can have arbitrary side effects.

JOB INSTANCE COMMAND

Every single job is represented by a job object command which allows to manipulate the job.

job# attribute [name [value]]

The job# attribute command allows to save job specific state information in job attributes. If called without any arguments, all existing attribute names for this job will be returned. If called with a name argument, the current value of the attribute will be returned. Non-existing attributes do not produce an error. Instead, an empty string is returned. Calling the option with a name and a value causes the value to be saved in the job attribute.

job# cget option

The job# cget command returns the current value of a configuration option. See the description of supported options below.

job# configure [option value ...]

The job# configure command manipulates configuration options. See the description of supported options below. A list describing all options is returned if the optional arguments are absent.

job# destroy

The job# destroy command destroys the job object. This command forces the object to change into the expired state. The scheduler will cleanup this object the next time it is active.

job# wait

The job# wait command blocks and processes events until the current job changes into the expired state.

JOB OPTIONS

Every job has associated configuration options which control when a job is activated and which Tcl command is bound to the job.

-command command

The -command option defines the Tcl command that is evaluated whenever the job is activated.

-error command

The -error option defines the Tcl command that is evaluated whenever the job causes an error. An empty error command causes Tnm to abort the running job and to call the Tcl bgerror procedure in order to signal this exception. Setting this option to a non-empty string causes Tnm evaluate the string without aborting the running job.

-exit command

The -exit option defines the Tcl command that is evaluated whenever the job ends its execution. This command allows to free resources that are associated with a job.

-interval time

The -interval option defines the time interval between two job activations in milliseconds. This number must be a positive integer value.

-iterations number

The -iterations option defines the total number of times that a job is activated. If this value reaches 0, the job will change its state to expired. Note, if the -iterations option is never used, it will also have the value 0 but nothing special happens to the job object.

-status state

The -status option provides access to the current job state. A job is always in one of the states waiting, suspended, running and expired. A job in the expired state will be removed from the system once the scheduler gets activated again. Suspended jobs are not activated by the job scheduler. A suspended job can be resumed by changing its state to running.

-tags tagList

The -tags option is used to tag jobs. Tags are a convenient way to group jobs together that perform a single task together. Tags are also convenient to relate jobs to network map objects and/or management functions.

-time time

The -time option returns the number of milliseconds until this job is activated the next time. This option is read-only.

SEE ALSO

scotty(1), Tnm(n), Tcl(n)

AUTHORS

Juergen Schoenwaelder <[email protected]>