Catch and throw

You can use catch and throw to manage the execution flow in an OmniMark program. 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.

Catch and throw versus function calls

catch and throw have much in common with function calls. Both declare and use parameters to pass information, and both cause a transfer in execution to a new part of the program. They differ in the following principal ways:

  • A function call causes the creation of a new execution scope. A throw initiates the collapsing of current execution scopes up to and including the scope in which the catch occurs.
  • A non-overloaded function body can be defined only once for a given function name. Multiple different catch clauses can be defined for the same catch name, so long as they occur in different lexical scopes. Which catch clause is executed depends on which is active at the time a throw occurs. Only one catch of a given name is active at any given point in program execution.
  • A catch does not have to use the full syntax of its declaration when it is defined in code. The names of the parameters used in a definition do not have to match those used in the declaration or any other definition—only the position or the heralds have to match. A definition does not have to define any of the parameters, but must define any it intends to use.

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 main loop of a simple server program.

  import "omtcp.xmd" prefixed by tcp.
  
  process
     local tcp.service service initial { tcp.create-service on 5432 }
  
     repeat
        local tcp.connection connection initial { tcp.accept-connection from service }
  
        using output as tcp.writer of connection
           submit tcp.reader of connection
     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:

  import "omtcp.xmd" prefixed by tcp.
  
  process
     local tcp.service service initial { tcp.create-service on 5432 }
  
     repeat
        local tcp.connection connection initial { tcp.accept-connection from service }
  
        using output as tcp.writer of connection 
           submit tcp.reader of connection
  
      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 or any of the find rules invoked by the submit, execution will transfer to 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:

  import "omtcp.xmd" prefixed by tcp.
  
  process
     local tcp.service service initial { tcp.create-service on 5432 }
  
     repeat
        local tcp.connection connection initial { tcp.accept-connection from service }
  
        using output as tcp.writer of connection 
           submit tcp.reader of connection
  
      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 clause 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 opaque external component. We don't bother handling #external-exception specially in the code above, because failure to handle 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 || "."
          

If the attempt to open the named file fails, an external exception is thrown 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

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):

  import "omtcp.xmd" prefixed by tcp.
  
  declare catch nap-time
  
  process
     local tcp.service service initial { tcp.create-service on 5432 }
  
     repeat
        local tcp.connection connection initial { tcp.accept-connection from service }
  
        using output as tcp.writer of connection 
           submit tcp.reader of connection
  
      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 except one is a request for information: 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 with a declare at the beginning 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. We can add information to our throws as well, 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:

  import "omtcp.xmd" prefixed by tcp.
  
  declare catch nap-time because value string reason
  
  process
     local tcp.service service initial { tcp.create-service on 5432 }
  
     repeat
        local tcp.connection connection initial { tcp.accept-connection from service }
  
        using output as tcp.writer of connection 
           submit tcp.reader of connection
  
      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* => s
     throw nap-time because s
          

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

OmniMark 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 clauses. 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.

  import "omtcp.xmd" prefixed by tcp.
  
  declare catch nap-time because value string reason
  
  global stream log-file-name
  
  process
     local tcp.service service
     local stream      server-log
  
     set service to tcp.create-service on 5432
  
     repeat
        local tcp.connection connection
  
        reopen server-log as file log-file-name
        set connection to tcp.accept-connection from service
        put server-log tcp.peer-ip of connection || date "=Y/=M/=D =h:=m:=s"
        using output as tcp.writer of connection 
           submit tcp.reader of connection
        close server-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 server-log was never executed and the log file would remain open. This is something OmniMark cannot clean up itself, since server-log belongs to a wider scope which is not being closed. We want the line close server-log to be executed always, whether there is an error or not. To ensure this, we use an always clause:

  import "omtcp.xmd" prefixed by tcp.
  
  declare catch nap-time because value string reason
  
  global stream log-file-name
  
  process
     local tcp.service service
     local stream      server-log
  
     set service to tcp.create-service on 5432
  
     repeat
        local tcp.connection connection
  
        reopen server-log as file log-file-name
        set connection to tcp.accept-connection from service
        put server-log tcp.peer-ip of connection || date "=Y/=M/=D =h:=m:=s"
        using output as tcp.writer of connection 
           submit tcp.reader of connection
  
      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 server-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* => s
     throw nap-time because s
          

When a throw happens, OmniMark closes scopes one by one until it finds a scope that contains a catch clause for that throw. As it does so, it executes any code in an always clause in each of those scopes, including the scope that contains the catch. So in this example, close server-log will be executed before the catch clause 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 maintain. 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):

  import "omtcp.xmd" prefixed by tcp.
  
  declare catch nap-time because value string reason
  
  global stream log-file-name
  
  process
     local tcp.service service
     local stream      server-log
  
     set service to tcp.create-service on 5432
  
     repeat
        local tcp.connection connection
  
        reopen server-log as file log-file-name
        set connection to tcp.accept-connection from service
        put server-log tcp.peer-ip of connection || date "=Y/=M/=D =h:=m:=s"
        using output as tcp.writer of connection 
           submit tcp.reader of connection
  
      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 server-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* => s
     throw nap-time because s
     
  
  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"