You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/SETTINGS.md
+26-16Lines changed: 26 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,27 +61,27 @@ Every Perl script run by PEB has a JavaScript settings object with an arbitrary
61
61
62
62
There are three methods to start a local Perl script:
63
63
64
-
***Clicking a link to a settings pseudo filename:**
64
+
***Clicking a link to a script settings pseudo filename:**
65
65
66
66
```html
67
67
<ahref="test.script">Start Perl script</a>
68
68
```
69
69
70
-
***Submitting a form to a settings pseudo filename:**
70
+
***Submitting a form to a script settings pseudo filename:**
71
71
72
72
```html
73
73
<formaction="test.script">
74
74
<inputtype="submit"value="Start Perl script">
75
75
</form>
76
76
```
77
77
78
-
***Calling a JavaScript function with a settings pseudo filename:**
78
+
***Calling a JavaScript function with a script settings pseudo filename:**
79
79
80
80
```javascript
81
81
peb.startScript('test.script');
82
82
```
83
83
84
-
This method creates an invisible form and submits it to the settings pseudo filename.
84
+
This method creates an invisible form and submits it to the script settings pseudo filename.
85
85
86
86
A minimal example of a JavaScript settings object for a Perl script run by PEB:
87
87
@@ -131,20 +131,32 @@ A JavaScript settings object for a Perl script run by PEB has the following prop
131
131
}
132
132
```
133
133
134
-
***scriptExitCommand**
135
-
``String`` containing the command used to gracefully shut down [an interactive Perl script](#interactive-perl-scripts) when PEB is closed
136
-
Upon receiving it, an interactive script must start its shutdown procedure.
137
-
138
-
***scriptExitConfirmation**
139
-
``String`` used to signal PEB that [an interactive Perl script](#interactive-perl-scripts) completed its shutdown
140
-
All interactive scripts must exit in 3 seconds after ``scriptExitCommand`` is given or any unresponsive scripts will be killed and PEB will exit.
141
-
142
134
## Interactive Perl Scripts
143
-
Each PEB interactive Perl script must have its own event loop waiting constantly for new data on STDIN for a bidirectional connection with PEB. Many interactive scripts can be started simultaneously in one browser window. One script may be started in many instances, provided that it has a JavaScript settings object with an unique name. Interactive scripts must also have the ``scriptExitCommand`` object property. The ``scriptExitConfirmation`` object property is not mandatory, but highly recommended for a quick shutdown of PEB.
135
+
Each PEB interactive Perl script must have its own event loop waiting constantly for new data on STDIN for a bidirectional connection with PEB. Many interactive scripts can be started simultaneously in one browser window. One script may be started in many instances, provided that it has a JavaScript settings object with an unique name.
144
136
145
137
Please note that interactive Perl scripts are not supported by the Windows builds of PEB.
146
138
147
-
Please also note that if a PEB instance crashes, it will leave its interactive scripts as zombie processes and they will start consuming large amounts of memory! Exhaustive stability testing has to be done when interactive scripts are selected for use with PEB! Even during normal operation interactive scripts use more memory than non-interactive scripts and their use should be carefully considered.
139
+
PEB interactive scripts should have ``$|=1;`` among their first lines to disable the built-in buffering of the Perl interpreter, which prevents any output before the script has ended.
140
+
141
+
When PEB is closing, it sends the ``SIGTERM`` signal to all interactive scripts to prevent them from becoming zombie processes. All interactive scripts must exit in 3 seconds after the ``SIGTERM`` signal is given by PEB.
142
+
All unresponsive scripts are killed before PEB exits. The ``SIGTERM`` signal may be handled by any interactive script for a graceful shutdown using the following code:
143
+
144
+
```perl
145
+
$SIG{TERM} = sub {
146
+
# your shutdown code goes here...
147
+
exit();
148
+
};
149
+
```
150
+
151
+
If a PEB instance crashes, it can still leave its interactive scripts as zombie processes consuming large amounts of memory. To prevent this scenario, all interactive scripts should test for a successful ``print`` on the STDOUT. This could be implemented using the following code:
152
+
153
+
```perl
154
+
print"output string"or shutdown_procedure();
155
+
156
+
subshutdown_procedure {
157
+
exit();
158
+
}
159
+
```
148
160
149
161
The following code shows how to start an interactive Perl script right after a local page is loaded:
150
162
@@ -169,8 +181,6 @@ The following code shows how to start an interactive Perl script right after a l
169
181
var container =document.getElementById('interactive-script-output');
0 commit comments