Stay-Resident pages

A Stay-Resident page is a long lived page that stays running within THT after output has been returned to the user. All future http requests using the same file path in the url will be handled by the proc main in the resident page. In other words, the page becometh an application. A Resident page has the extension .thr

The [main] proc.

All Resident pages must define main as:

  proc main {code args} {...}

If a page is resident, then each time a request comes in, [main N] is called. The value N contains the number of times this page has been called (starting from 1). The value 0 is reserved for application initialization.

When the application is to be destroyed, it is called with code = -1.

Here is an example:

<TITLE>Welcome Home</TITLE>
 <H1>Hello World</H1>

<?tht

proc main {code args} {
  if {$code<0} {
    # Cleanup: we're going down.
  } elseif {$code == 0} {
    # Init, or not running as resident.
  } elseif {$code < 4} {
     echo "<B>Hit reload to go to next page: $code of 4.</B>"
  } else {
     echo "<B>Last page: hit reload to startover!</B>"
     return -code break
  }
}

main 0

?>

Page Termination

Before a resident page is terminated, main is called with:

  main -1 -reason R -when T

where T is the time and R is one of:

Code	Description
cpu	max cpu time exhasted, will error out in 2 seconds
idle	page idle-timeout reached, will unload in 60 seconds
modified	page will reload now as it has changed on disk

There are three ways a resident page may decide to destroy itself and no longer stay resident:

[main] does a [return -code break].
the page calls [tht unresident]
the page generate an error, or call [error MSG].

In any case the next invocation will re-load the page.

Resource Limits

When using Tcl8.5+ a Resident page is subject to cpu processing time limits. Each request is given a default timeslice (default is 60 seconds). When this is exceeded, [main -1 ...] gets called, signalling 2 seconds of grace time to complete. After this the page will error out causing a traceback. The default time can be changed, for example to 120 seconds with -icfg "cpu:time 120" in the config file.

Similarly, an idle timeout, is defined (default 10 minutes) that unloads idle pages. To change this interval, call [tht idletimeout N]. Again, [main -1 ...] is called to signal termination.

Finally, if the file changes on disk, then the next invocation of a request will initiate a terminate to start a new cycle.

Extensions

When a termination call occurs (ie. [main -1]), one can use [return -code continue N] can request an extension be added to grace time (<= to the hard limit). If N<0 or not an integer, the hard limit is requested.

Usage

There are several different methods of invoking THT, including: as a CGI, with FastCGI with SockCGI or natively within THS. All but the first (one-shot CGI) support Stay-Resident pages.

It should be generally understood that all pages in THT share the same process. That is, threads are not used (currently), so a page hang will block others. However, cpu limiting per interp in Tcl8.5 can minimize that shortcoming, as can putting one application per THT instance. Moreover, Tcl does support threads and so this may be a future option.

Note: A Resident pages should use echo, include, or tht eval for output as the page is interpreted only the first time visited.

PDQI
	THT / Stay-Resident	Search Print Login