 |
 |
|
|
       |
|||
|
|||||||||
|
|
|||||||||
| Related Syntax | |||||||||
| Catch and throw | |||||||||
You can use catch and throw to manage the execution flow in your OmniMark programs. Catch and throw is a powerful addition to the flow handling features of OmniMark, allowing you to make major redirections of program flow in a safe and structured way.
It is probably easiest to think of catch and throw as an exception handling mechanism. What is an exception? Essentially anything that is an exception to the normal flow of your processing. Some exceptions come whether you want them or not, in the form of run-time program errors or failure to communicate with the world outside your program. Others are simply an expression of the way you choose to solve your programming problem.
It is often the case that a simple piece of code can handle 90% of all cases. The other 10% are exceptions that require significantly different processing. Dividing a problem up into "normal" cases and "exceptions" is a convenient way to simplify and organize your code. This does not mean that the exceptions are errors or even unexpected. Often the exceptional cases are what you are most interested in. Programming with exceptions is simply a technique for designing an algorithm to solve a particular problem.
Catching program errors
The simplest use of catch and throw is to allow your program to recover when something goes wrong. Consider the following code, which contains the server loop of a simple server program.
include "omioprot.xin"
include "omtcp.xin"
process
local TCPService my-service
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
set my-connection to TCPServiceAcceptConnection my-service
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
again
Any error in the program or with the TCP connection will cause this program to terminate, since there is nothing to handle the error. Server programs should be written to stay running if at all possible, so we need to do something to allow the program to recover:
include "omioprot.xin"
include "omtcp.xin"
process
local TCPService my-service
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
set my-connection to TCPServiceAcceptConnection my-service
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
catch #program-error
again
We have added only a single line, but this version of the program is much more robust. If any error occurs while in the repeat loop of any of the find rules invoked by the submit, execution will transfer to the line "catch #program-error". Along the way, OmniMark will clean up after itself. Local scopes will be terminated, and resources released.
No attempt is made to salvage the work that was in progress when the error happened. That work, and all the resources associated with it, are thrown away. But the server will stay up and running and ready to receive the next request.
Of course, it would be nice to know that the error occurred and why it occurred. #program-error makes information available so that we can act on the error, or at least report it. To ensure that errors get logged, we can rewrite the program like this:
include "builtins.xin"
include "omioprot.xin"
include "omtcp.xin"
process
local TCPService my-service
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
set my-connection to TCPServiceAcceptConnection my-service
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
catch #program-error code c message m location l
log-message ( "Error "
|| "d" % c
|| " "
|| m
|| " at "
|| l
|| " time "
|| date "=Y/=M/=D =h:=m:=s"
)
again
Note that the catch line guards everything that follows from being executed. The only way into the code of a catch block is to be caught by that catch.
So far, we have seen nothing of the "throw" part of throw and catch. This is because OmniMark itself throws to #program-error. OmniMark can also throw to #external-exception if it has a problem communicating with the external world (such as being unable to open a file or communicate successfully with an OMX component). We don't bother to catch #external-exception in the code above, because the failure of a program to catch an external exception is itself a program error, which causes a throw to #program-error. In other circumstances we might want to use #external-exception explicitly. Suppose one of the find rules in our server program tried and failed to open a file:
find "open file " letter+ => foo
output file foo
catch #external-exception
output "Unable to open file " || foo || "."
Suppose the attempt to open the named file fails. This causes an external exception at the first output action. We catch the exception and provide alternate output. The program then continues as if nothing had happened.
Now our server is more robust still, since an error opening a file will not cause processing of the current request to be aborted. Instead, the client will receive the error message we output along with any other information the request generates.
Exception handling
When it comes to throwing things, OmniMark does not get to have all the fun. We can create our own exceptions, throw our own throws, and define our own catches. Let's write our own exception to let us shut down the server by remote control (to simplify things, we've left out some of our earlier enhancements):
include "builtins.xin"
include "omioprot.xin"
include "omtcp.xin"
declare catch nap-time
process
local TCPService my-service
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
set my-connection to TCPServiceAcceptConnection my-service
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
catch #program-error
again
catch nap-time
find "sleep"
throw nap-time
Here we have a classic case of an exception. Every request to our server is a request for information. Every request except one. The "sleep" request is an instruction to the server to shut itself down. This is the exceptional case and we handle it with an exception.
In the exceptional case that we are shutting down the server, we need to jump out of the connection loop. We do this with a catch outside the loop. The catch is called "nap-time". Catches are named so that we can have more than one and have each one catch something different. Like all names introduced into an OmniMark program, the name of a catch must be declared, which we do in the first line of the program. We place the catch outside the request handling loop. Because OmniMark cleans up after itself while performing a throw, all the resources belonging to the local scope inside the loop are properly closed down. Then, since we are outside the loop and at the end of the process rule, the program simply ends, shutting down the server.
The throw itself is very simple. Having detected the exceptional case (the "sleep" request) we simply throw to the appropriate catch by name. OmniMark handles everything else.
Throwing additional information
When OmniMark throws to #program-error or #external-exception, it adds additional information in the form of three parameters: code, message, and location. It is only fair that we be allowed to pass additional information with our throws as well. We can do this by adding parameters to our catch declaration, following the form of a function definition. Let's add the capability to log the reason for putting a server to sleep:
include "builtins.xin"
include "omioprot.xin"
include "omtcp.xin"
declare catch nap-time because value stream reason
process
local TCPService my-service
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
set my-connection to TCPServiceAcceptConnection my-service
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
catch #program-error
again
catch nap-time because r
log-message ( "Shut down because "
|| r
|| " Time: "
|| date "=Y/=M/=D =h:=m:=s"
)
find "sleep" white-space* any* => the-reason
throw nap-time because the-reason
Here the find rule captures the rest of the "sleep" message and uses it as a parameter to the throw. The catch receives the data and uses it to create the appropriate log message.
Cleaning up after yourself
We said that OmniMark cleans up after itself, and it does. It cleans up everything it knows about. But this may still leave you with cleanup of your own to do. Or there may simply be things that always have to be done, even if an exception occurs. For this, OmniMark provides the "always" keyword. Let's suppose that our server does its own connection logging, while still using OmniMark's logging facility for errors. We want the connection log file closed between requests to make it easy to cycle the log files, so we open and close the log file for each connection.
declare catch nap-time because value stream reason
include "builtins.xin"
include "omioprot.xin"
include "omtcp.xin"
global stream log-file-name ;should be initialized from the command line
process
local TCPService my-service
local stream my-log
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
reopen my-log as file log-file-name
set my-connection to TCPServiceAcceptConnection my-service
put my-log TCPConnectionGetPeerIP my-connection || date "=Y/=M/=D =h:=m:=s"
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
close my-log
catch #program-error code c message m location l
log-message ( "Error "
|| "d" % c
|| " "
|| m
|| " at "
|| l
|| " time "
|| date "=Y/=M/=D =h:=m:=s"
)
again
catch nap-time because reason
log-message ( "Shut down because "
|| reason
|| " Time: "
|| date "=Y/=M/=D =h:=m:=s"
)
In this code, a problem processing the request would cause a throw to #program-error. This would mean that the line "close my-log" was never executed and the log file would remain open. (This is something OmniMark can't clean up itself, since the stream my-log belongs to a wider scope which is not being closed.) We want the line "close my-log" to be executed always, whether there is an error or not. To ensure this, we use "always":
declare catch nap-time because value stream reason
include "builtins.xin"
include "omioprot.xin"
include "omtcp.xin"
global stream log-file-name ;should be initialized from the command line
process
local TCPService my-service
local stream my-log
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
reopen my-log as file log-file-name
set my-connection to TCPServiceAcceptConnection my-service
put my-log TCPConnectionGetPeerIP my-connection || date "=Y/=M/=D =h:=m:=s"
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
catch #program-error code c message m location l
log-message ( "Error "
|| "d" % c
|| " "
|| m
|| " at "
|| l
|| " time "
|| date "=Y/=M/=D =h:=m:=s"
)
always
close my-log
again
catch nap-time because reason
log-message ( "Shut down because "
|| reason
|| " Time: "
|| date "=Y/=M/=D =h:=m:=s"
)
find "sleep" white-space* any* => the-reason
throw nap-time because the-reason
When a throw happens, OmniMark closes scopes one by one until it finds a scope that contains a catch for that throw. As it does so, it executes any code in an always block in each of those scopes, including the scope that contains the catch. So in this example, the "close" line will be executed before the catch block is executed, no matter where or why an error occurs.
Programming with exceptions is a powerful technique that can make your programs both more reliable and easier to read and write. Here is our full server program with all our catch and throw functionality, plus logging of our external exception (but minus the find rules that do the rest of the work):
declare catch nap-time because value stream reason
include "builtins.xin"
include "omioprot.xin"
include "omtcp.xin"
global stream log-file-name ;should be initialized from the command line
process
local TCPService my-service
local stream my-log
set my-service to TCPServiceOpen at 5432
repeat
local TCPConnection my-connection
local stream my-response
reopen my-log as file log-file-name
set my-connection to TCPServiceAcceptConnection my-service
put my-log TCPConnectionGetPeerIP my-connection || date "=Y/=M/=D =h:=m:=s"
open my-response as TCPConnectionGetOutput my-connection
using output as my-response
do
submit TCPConnectionGetLine my-connection
done
catch #program-error code c message m location l
log-message ( "Error "
|| "d" % c
|| " "
|| m
|| " at "
|| l
|| " time "
|| date "=Y/=M/=D =h:=m:=s"
)
always
close my-log
again
catch nap-time because reason
log-message ( "Shut down because "
|| reason
|| " Time: "
|| date "=Y/=M/=D =h:=m:=s"
)
find "sleep" white-space* any* => the-reason
throw nap-time because the-reason
find "open file " letter+ => foo
output file foo
catch #external-exception identity i message m location l
output "Unable to open file " || foo || "."
log-message ( "Error "
|| i
|| " "
|| m
|| " at "
|| l
|| " time "
|| date "=Y/=M/=D =h:=m:=s"
)
|
Related Syntax #external-exception #program-error always catch is catchable is thrown rethrow throw using catch |
| ---- |
