diff options
author | Nat Goodspeed <nat@lindenlab.com> | 2019-12-10 11:51:38 -0500 |
---|---|---|
committer | Nat Goodspeed <nat@lindenlab.com> | 2020-03-25 15:28:17 -0400 |
commit | dd98717caa712c17ef6a8f187754670b614ab253 (patch) | |
tree | d10e48b514bcfb277cc02950248c4989727fccee | |
parent | 960593fd5eedcc63632fe4e0e3b71ac4afc91d11 (diff) |
DRTVWR-494: Document LLMainThreadTask class.
-rw-r--r-- | indra/llcommon/llmainthreadtask.h | 28 |
1 files changed, 28 insertions, 0 deletions
diff --git a/indra/llcommon/llmainthreadtask.h b/indra/llcommon/llmainthreadtask.h index 526374981a..2e0583d104 100644 --- a/indra/llcommon/llmainthreadtask.h +++ b/indra/llcommon/llmainthreadtask.h @@ -21,6 +21,34 @@ #include <type_traits> // std::result_of #include <boost/signals2/dummy_mutex.hpp> +/** + * LLMainThreadTask provides a way to perform some task specifically on the + * main thread, waiting for it to complete. A task consists of a C++ nullary + * invocable (i.e. any callable that requires no arguments) with arbitrary + * return type. + * + * Instead of instantiating LLMainThreadTask, pass your invocable to its + * static dispatch() method. dispatch() returns the result of calling your + * task. (Or, if your task throws an exception, dispatch() throws that + * exception. See std::packaged_task.) + * + * When you call dispatch() on the main thread (as determined by + * on_main_thread() in llthread.h), it simply calls your task and returns the + * result. + * + * When you call dispatch() on a secondary thread, it instantiates an + * LLEventTimer subclass scheduled immediately. Next time the main loop calls + * LLEventTimer::updateClass(), your task will be run, and LLMainThreadTask + * will fulfill a future with its result. Meanwhile the requesting thread + * blocks on that future. As soon as it is set, the requesting thread wakes up + * with the task result. + * + * Under some circumstances it's necessary for the calling thread to hold a + * lock until the task has been scheduled -- yet important to release the lock + * while waiting for the result. If you pass a LockStatic<T> to dispatch(), + * a secondary thread will unlock it before blocking on the future. (The main + * thread simply holds the lock for the duration of the task.) + */ class LLMainThreadTask { private: |