Aborting searches

As mentioned in the section called “The search callback thread”, the search callback gets executed by a separate execution thread. It's possible that the search function could take some non-trivial amount of time to run the entire search, but it's a separate execution thread, and LibCXXW's connection thread continues with its duties, without delay. It's possible that additional text gets typed into the input field while the search callback is still searching, so the eventual search results will be stale; or the search field loses keyboard input focus.

The search callback gets invoked again only after the current search finishes and the search callback returns with the original results. There's only one execution thread. LibCXXW takes care of starting and stopping it the search thread, as needed. However the search thread can only be stopped after the search callback returns. It's not possible to stop C++ execution threads unilaterally.

A search callback can use the abort mcguffin as the means of getting notified that the current search should stop:

         // ...

See the LIBCXX documentation for a complete explanation of its mcguffin design pattern. The connection thread releases its only reference on the opaque reference-counted object to indicate that the search results are stale, and the mcguffin object gets destroyed, invoking the ondestroy() lambda.

searchinputfield.C demonstrates the advantages of using search abort mcguffins. Its search callback artificially pauses for one second when the search string is three or more characters. Between three and six characters the search callback uses an abort mcguffin and returns without any results immediately, before the full second is up. The search popup gets closed immediately without showing any search results until the slow search function finally completes.

For matching search strings of seven and more characters, the search results will be visibly stale, as typing continues, until they eventually catch up.