Add FAQ entry for dealing with long functions interruption

[CharlesB2]

I've spent some time figuring out how to correctly interrupt a long-running function when a SIGINT occurs, so I thought this entry could be useful.

[bjodah]

I've dabbled with interrupts so I appreciate this. What would be an example of interruption_error()? Is there any such default exception in C++ stdlib? Or do one need to create one and specify it's translation to Python's KeyboardInterrupt using pybind11?

[CharlesB2]

Sorry I didn't include it, it's a user-defined exception since C++ stdexcept has no equivalent:

class interruption_error: public exception {
public:
    const char* what() const noexcept{
        return "Interruption signal caught."; 
    }
};

[wjakob]

Minor wording request.

[wjakob]

Thanks!

[eacousineau]

Nice! From tinkering with this, I think this could possibly be simplified; will PR a small change.

Reading the docs, it looks like the exception would have already been raised if this function returns non-zero:
https://docs.python.org/3.6/c-api/exceptions.html?highlight=pyerr_checksignals#c.PyErr_CheckSignals
https://docs.python.org/2.7/c-api/exceptions.html?highlight=pyerr_checksignals#c.PyErr_CheckSignals

So rather than create a redundant KeyboardInterrupt, it looks like you can just throw py::error_already_set. The following seems to work for me:

  m.def("stuff", []() -> void {
    while (true) {
      if (PyErr_CheckSignals() != 0) {
        throw py::error_already_set();
      }
      using namespace std::chrono_literals;
      std::this_thread::sleep_for(50ms);
    }
  });

try:
  m.stuff()
  assert False
except KeyboardInterrupt:
  print("[ Done ]")

Full code here: https://github.com/eacousineau/repro/blob/f791b817ae88743cff66f7214f40a487ae99d843/python/pybind11/custom_tests/test_tmp.cc

[eacousineau]

Posted: #2007

[CharlesB2]

Great, much simpler with py:error_already_set!