Document Parser and Instance exception behavior

[Marcono1234]

Follow-up for #118 (comment) / #118 (comment)

Resolves #98
(as you mentioned there, it is expected / acceptable that non-WasmEngineException are thrown)

I hope the wording is ok like this, but please let me know if you want it to be changed.

[andreaTP]

Thanks for putting this up!
Left a nitpick.

it is expected / acceptable

I don't want to leave the wrong impression here.
I'm not trying to downplay, but that's kind of the same behavior across several runtimes I have experimented with.
If you have a better alternative, please let's discuss.

[andreaTP]

I would not stress:

but callers should be prepared to handle any kind of {@code* RuntimeException}

isn't it "always true"?

[Marcono1234]

No, at least not for all libraries. Many (including the JDK) often try to document all exceptions with @throws / throws, and any undeclared exception is considered a bug. That helps the user to determine which exact exceptions to catch, instead of wildcard catch (Exception) or catch (RuntimeException).

Though I understand that ensuring this for Endive might not be easily possible, due to Wasm being quite complex and there being lots of potential error cases (and detecting all might cause overhead).

So I think it would be useful to explicitly point out to users that just catching WasmEngineException is probably not enough.

Or the question is, is a non-WasmEngineException only expected for malformed code?
(But currently even Endive itself has explicit throw new RuntimeException; see #151).

[Marcono1234]

If you have a better alternative, please let's discuss.

Not really. As mentioned in #98 I see mainly two alternatives:

• add checks to prevent these runtime exceptions (respectively throw dedicated Endive exceptions)

  Not sure if this is feasible; it might decrease performance and make the code very verbose.
  On the other hand it might make troubleshooting easier, and possibly avoids other incorrect behavior for invalid code which Endive currently accidentally permits.

• do something like catch (RuntimeException e) throw new WasmEngineException(e)

  Though there might be multiple places where this is necessary, and it might be possible that some are missed or added in the future, causing the RuntimeException to be propagated unwrapped.
  The main issue with this is also that it might hide actual bugs as WasmEngineException, making it look like the exception was intended.

But neither of these is really ideal.

[andreaTP]

ok, I think we can move forward with this, is anyways an improvement.

Thanks for the discussion!