Synchronous vs. Asynchronous methods

Synchrony?

A synchronous method completes its entire task before returning to the caller. An asynchronous method starts the task in the background and returns to the caller immediately.

Some methods are more synchronous than others.

In this project, there are two distinct meanings of "synchronous" method:

1. A method which blocks the current Xojo thread. ("soft")
2. A method which blocks the current OS-level thread. ("hard")

A "hard" synchronous method will cause the entire application to block until it returns. In single-threaded console applications, this is just fine; in GUI applications it's an absolute disaster.

A "soft" synchronous method will block the Xojo thread that calls it, but will not block the entire application.

Implications

Most methods of EasyHandle, MultiHandle, ShareHandle, MultipartForm, and ListPtr are (or should be treated as) "hard" synchronous. For quick operations like setting an option or appending a form element this isn't a problem. For potentially very long operations like downloading a file, however, it is a major concern.

libcURL provides a solution via its curl_multi API. All the EasyHandles associated with a MultiHandle will perform a small part of their transfer and then return. This allows the "hard" synchronous nature of the method to be amortized over several invocations.

This means that a Xojo thread can invoke the method and then yield (if needed) to the next thread, or be rigged to invoke the method on the main event loop for asynchronous operation.

tldr

All synchronous request methods of cURLClient are "soft" synchronous and will block the Xojo thread which invokes them; all asynchronous methods run on the main event loop.