summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNat Goodspeed <nat@lindenlab.com>2019-12-10 11:51:38 -0500
committerNat Goodspeed <nat@lindenlab.com>2020-03-25 15:28:17 -0400
commitdd98717caa712c17ef6a8f187754670b614ab253 (patch)
treed10e48b514bcfb277cc02950248c4989727fccee
parent960593fd5eedcc63632fe4e0e3b71ac4afc91d11 (diff)
DRTVWR-494: Document LLMainThreadTask class.
-rw-r--r--indra/llcommon/llmainthreadtask.h28
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: