Debugging

Hare supports a number of features and standards to aid in debugging. Hare programs are built with debugging features enabled by default; to disable them pass the -R (“release”) flag to hare build.

Debug symbols

Hare has limited support for DWARFv5 debug symbols, which is compatible with a number of popular debugging tools, such as gdb. Hare supports mapping addresses to line numbers and source files, as well as basic stack unwinding. Getting information about type details and locals is not supported.

Note

Hare identifiers such as hash::fnv are rewritten to use dots in place of namespace separators, so this example becomes hash.fnv.

Runtime errors

The following error cases are detected by the Hare runtime. For programs built in debug mode, a stack trace is shown when an error is detected.

• Buffer overflows/out-of-bounds read or write

• Heap corruption

  • Invalid/double free

  • Use-after free [1]

• Out of memory errors [2]

• Type assertion failures

• Unhandled errors

• Errors reported by signals, such as: [3]

  • Arithmetic errors (e.g. divide by zero)

  • Bus errors (e.g. unaligned writes)

  • Illegal instructions

  • Segmentation faults (e.g. null pointer dereference)

  • Stack overflows

Danger

Hare provides escape hatches which can be used to circumvent these runtime checks, such as arrays of indefinite length (e.g. [*]int). When using these features, the programmer assumes responsibility for ensuring the correctness of their code.

Caveats

[1]

Handled on a best-effort basis. It is not always possible for the runtime to detect these errors. Note also that memory error detection is unavailable when linking Hare programs with libc, as we use libc’s memory allocator instead of managing memory ourselves.

[2]

On systems with overcommit (such as Linux), memory allocations may appear successful at the time of allocation, but cause unexpected problems at the time of use. There is not much Hare can or should do about that.

[3]

Only detected by the runtime in debug mode. In release mode these errors are handled by the operating system’s default signal handler.

Slice or array out of bounds

The “slice or array out of bounds” message is a runtime assertion which occurs when accessing an index of a slice or array which falls outside of its defined length.

This error message indicates that the programmer has made a design error.

export fn main() void = {
     let x: [3]int = [1, 2, 3];
     x[0]; // okay
     x[1]; // okay
     x[2]; // okay
     x[3]; // abort

     x[0..2];  // okay
     x[0..10]; // abort
};

This can occur when using:

• Indexing expressions: x[4]

• Slicing expressions: x[2..4]

• Slice assignment expressions: x[..] = y[..]

• Insert or delete expressions

Note

When using an insert expression, it is legal to insert a value at the end of a slice, such that the index equals len(slice). This index is not valid in any other kind of expression. The first index which will cause this runtime assertion to occur when using an insert expression is len(slice)+1.

Recommended solutions

• Ensure that you are computing indices correctly. For example, look for off-by-one errors. Note that slices and arrays in Hare are zero-indexed, so the first item is at 0 and the last item is at len(x) - 1.

• Test that your index is less than the length of the object before accessing a value at that index:

  let x: [3]int = [0...];
  let ix = 10z;
  if (ix < len(x)) {
          x[ix]; // okay
  };
  

Type assertion failed

The “type assertion failed” message is a runtime assertion which occurs when the as operator is used on a tagged union value which is storing a value of a type which differs from the right-hand side of the as operation.

This message indicates that the programmer has made a design error.

export fn main() void = {
     let x: (int | uint) = 10i;  // value is of type int
     x as int;                   // okay
     x as uint;                  // abort
};

Recommended solutions

• Determine why the value was of a different type than the programmer expected at this point.

• Replace the as expression with a match expression which handles more possible cases.

  // Before:
  let x: (int | uint) = 10i;
  x as uint; // Will fail if x is an int
  
  // After:
  let x: (int | uint) = 10i;
  match (x) {
  case let x: int =>
          // x is an int
  case let x: uint =>
          // x is a uint
  };
  

Out of memory

The “out of memory” message is a runtime assertion which occurs when a memory allocation fails without being handled by the programmer.

export fn main() void = {
     let x: *int = alloc(42);         // might fail
     let x: []int = alloc([1, 2, 3]); // might fail
     append(x, 42);                   // might fail
     insert(x[0], 42);                // might fail
};

Recommended solutions

• If using the alloc expression, use a nullable pointer type. In the event of an allocation failure, the value will be null and this runtime assertion will not occur.

Warning

Improving support for managing out-of-memory conditions in Hare programs is a design area planned for future improvement.

Static insert/append exceeds slice capacity

The “static insert/append exceeds slice capacity” message is a runtime assertion which occurs when a static append or static insert operation would exceed the capacity of the slice. When using static insert and append, the programmer must ensure that their program will not exceed the amount of space allocated for the underlying slice.

This message indicates that the programmer has made a design error.

export fn main() void = {
     let x: [4]int = [0...];
     let y: []int = x[..0];
     static append(x, 1);
     static append(x, 2);
     static append(x, 3);
     static append(x, 4);
     static append(x, 5);  // abort
};

Recommended solutions

• Test that the capacity is sufficient before performing an insert or append, and handle the case where there is insufficient space.

• Increase the size of the underlying array.

• If better suited to your use-case, switch to dynamically allocated slices (i.e. drop the static keyword).

Warning

Hare will not automatically move stack- or statically-allocated slices to the heap when they are passed to append et al; attempting to do so will crash your program with a memory error. You must either heap-allocate the slice from the start, or allocate a copy of the original slice, if you want to change to heap-allocated slices.

Execution reached unreachable code

The “execution reached unreachable code” message is a runtime assertion which occurs when the program reaches an area in the generated code which was thought to be impossible by the compiler designers. This is a safeguard put in place by the compiler to avoid introducing vulnerabilities or unexpected behavior if such situations were to arise anyway.

The most common cause of this error is that the programmer failed to consider all possible cases when writing a match expression. Currently the Hare compiler does not perform exhaustivity analysis on match expressions at compile-time; this error can be raised at runtime instead.

This can also occur in situations where a variable used in match or switch expression has an illegal value. If you cast an integer to an enum type, the language does not test that the final value is a valid value for that enumeration; switching against this value may lead to this error. Similarly, if you create an invalid tagged union (through pointer manipulation, for example), this error may occur when using a match expression. It may also occur in similar edge cases, such as in the case of stack or heap corruption. Most of these cases are rare, unless your code is doing something unusual the most likely explanation is a non-exhaustive match expression or an invalid enum cast.

Otherwise, this message indicates that a bug is present in the Hare compiler. Please report it to the hare-users mailing list.

export fn main() void = {
     let x: (u8 | u16 | u32 | u64) = 0u64;
     match (x) {
     case u8 => // ...
     case u16 => // ...
     case u32 => // ...
     };
};

Recommended solutions

• Double check that your match expression handles all possible cases

• Check that the objects being matched or switched against have sane values

• Otherwise, report the issue upstream

Slice allocation capacity smaller than initializer

The “slice allocation capacity smaller than initializer” message is a runtime assertion which occurs when allocating a slice with both an initializer and a desired capacity using an alloc expression if the provided initializer has a greater length than the desired capacity.

This message indicates that the programmer has made a design error.

export fn main() void = {
     let capacity = 3z;
     let x: []int = alloc([1, 2, 3, 4, 5], capacity); // abort
};

Recommended solutions

• Ensure that the initializer has no excess elements

• Increase the requested capacity

Error occurred

The “error occurred” message is a runtime assertion which occurs when the error assertion operator (!) is used and an error occurred at runtime.

This message indicates that the programmer has made a design error.

use fmt;

// Use `hare run main.ha >/dev/full` to simulate this error
export fn main() void = {
     fmt::println("Hello world!")!; // abort
};

Recommended solutions

• Determine why an error occurred where one was not expected

• Use a match expression to handle the possible error cases explicitly

• Use the error propagation operator (?) and update the return type to pass the error to the function which called the relevant code

Note

Using haredoc to look up the function which produced the error is a good way to quickly find out what possible outcomes you might need to handle.