18.15.1 Exceptions

Exceptions in Poke are values of type Exception, which is a struct defined like this:

type Exception =
  struct
  {
    int<32> code;
    string msg;
  };

where code identifies the type of the exception, and msg is supposed to be a textual description of the exceptional situation.

You can use codes 255 and higher for your own exceptions. For example:

raise Exception { code = 255; msg = "double upset event" };

User-defined exceptions should be registered using exception_code function. For example:

var E_my_exception = Exception {
  code = exception_code,
  msg = "double upset event",
};

where the E_my_exception.code is a unique number greater than or equal to 255.

Exception codes in the range 0..254 are reserved for poke. These are used in predefined exceptions which are standard, and have specific meanings:

E_generic

Generic error.

E_out_of_bounds

Out of bounds exception. This can be raised when accessing containers, like arrays and strings.

E_eof

End of file exception. This can be raised when mapping in the IO space.

E_elem

Invalid element exception. This is raised when attempting to access union fields that do not exist.

E_constraint

Constraint violation exception. This is raised when a constraint exception fails while mapping or constructing a struct.

E_conv

Conversion exception. This can be raised while casting values.

E_map_bounds

Out of map bounds exception. This can be raised while modifying a mapped value in a way it would violate its declared boundary (like the size of a mapped array.)

E_map

No map exception. This is raised when trying to map a not mapped value.

E_div_by_zero

Division by zero exception.

E_no_ios

No IOS exception. This is raised when the IO space is accessed but there is no IO space.

E_no_return

No return exception. This is raised when the end of a void function is reached.

E_io

Generic IO exception.

E_io_flags

Invalid flags were tried while opening an IO device.

E_assert

Assertion failure exception. This is raised by assert statement.

E_overflow

This exception is raised when signed overflow is detected in an arithmetic operation.

E_perm

This exception is raised when some operation can’t be performed due to incorrect (lack of) permissions or capabilities. An example is writing to a read-only IO space.

The exception codes of the standard exceptions are available in the form of EC_* variables. For example, this how you would raise an IO error with a particular message:

raise Exception { code = EC_io,
                   msg = "fluzo capacitator overheat impedes IO" }