This is documentation for Mathematica 5, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.1)

Documentation / Mathematica / Add-ons & Links / J/Link / Part 1. Installable Java: Calling Java from Mathematica /

1.2.13 Periodical Tasks

Section 1.2.7 described the ShareKernel function and how it allows Java and the notebook front end to share the kernel's attention. A side benefit of this functionality is that it becomes easy to provide a means whereby users can schedule arbitrary Mathematica programs to run at periodical intervals during a session. Say you have a source that provides continuously updated financial data and you want to have some variables in Mathematica constantly reflect the current values. You have written a program that goes out and reads from the source to get the information, but you have to manually run this program all the time while you are working. A better solution would be to set up a periodical task that pulls the data from the source and sets the variables every 15 seconds.

Controlling periodical tasks.

You can set up such a task with the AddPeriodical function:

AddPeriodical returns an integer ID number that you must use to identify the task—for example, when it comes time to stop scheduling it by calling RemovePeriodical. AddPeriodical relies on kernel sharing, so it calls ShareKernel if it has not already been called. There is no limit on the number of periodicals that can be established. The granularity of the scheduling interval is integer seconds, so you cannot use .1 as the delay and have your task executed every tenth of a second.

After scheduling the above task, updateFinancialData[] will be executed every 15 seconds while the kernel is idle. Note that periodical tasks are run only when the kernel is not busy—they do not interrupt other evaluations. If the kernel is in the middle of another evaluation when the allotted 15 seconds elapses, the task will wait to be executed until immediately after the computation finishes. Any such delayed periodicals are guaranteed to be executed as soon as the kernel finishes with the current computation. They cannot be indefinitely delayed if the user is busy with numerous computations in the front end or in Java. The converse to these facts is also true—if a periodical is executing when the user evaluates a cell in the front end, the evaluation will not be able to start until all periodicals finish, but it is guaranteed to start immediately thereafter.

To remove a single periodical task, use RemovePeriodical, supplying the ID number of the periodical as the argument. To remove all periodical tasks, use RemovePeriodical[Periodicals[]]. Periodical tasks are all removed if you call UnshareKernel[] with no arguments, which turns off all kernel sharing. You would then need to use AddPeriodical again to reestablish periodical tasks.

You can reset the scheduling interval for a periodical task by calling SetPeriodicalInterval, which is new in J/Link 2.0. This line makes the financial data periodical execute every 10 seconds, instead of 15 as shown above:

SetPeriodicalInterval[id, 10]

Sometimes you might want to change the interval for a periodical task or remove it entirely from within the code of the task itself. $ThisPeriodical is a variable that holds the ID of the currently executing periodical task. It will only have a value during the execution of a periodical task. You use $ThisPeriodical from within your periodical task to obtain its ID so that you can call RemovePeriodical or SetPeriodicalInterval.

Periodical tasks do not necessarily have anything to do with Java, nor do they need to use Java. Technically, Java does not even need to be running. However, because Java is used by the internals of ShareKernel to yield the CPU, if Java is not running then setting a periodical task will cause the kernel to keep the CPU continuously busy. Periodical task functionality is included in J/Link because it is a simple extension to ShareKernel, and it does have some nice uses in association with Java.

A final note about periodical tasks is that they do not cause output to appear in the front end. Look at this attempt:

The programmer expects to get hello printed in his notebook every 10 seconds, but nothing happens. During the time when periodicals are executed, $ParentLink is not assigned to the front end (or Java). Results or side effects like Print output, messages, or graphics vanish into the ether.

Before proceeding, let's clean up the periodical tasks we created: