feat: add method CancelWithError()

[jcmfernandes]

I'm interested in knowing if the execution was cancelled, and I don't want to rely on string matching the error message to know it.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[adonovan]

Thanks for this PR.

It is crucial that cancellation preserve the backtrace of the Starlark call stack so that the user can tell what function was interrupted by cancellation. The existing code in Call will cause the leaf error (cancellation) to be wrapped by EvalError, if it's not already an EvalError, so I think it should work correctly. But can you add a test (or modify your current test) so that a stack of calls f->g->h is cancelled while h is running (e.g. counting to infinity), and assert that the resulting error has both (a) a call stack showing f, g, h and responds to errors.Is(err, Cancelled)?

[jcmfernandes]

Hey @adonovan, thanks for the review. I addressed your feedback. Let me know what you think.

[adonovan]

This is not how to wait for an event; use a semaphore (sync.WaitGroup) or just a channel.

But why not just have the ready function cancel its own Thread? The concurrency of polling is not what's being tested here. The Starlark program then reduces to:

def f(): g()
def g(): h()
def h(): cancel()

and the cancel builtin function becomes:

"cancel": starlark.NewBuiltin(...) {
		thread.CancelWithError(cancelErr)
		return starlark.None, nil
}

[jcmfernandes]

I see value in testing internally (sync?) and externally (async?) triggered cancellations, but I'm happy to change it.