From dd98717caa712c17ef6a8f187754670b614ab253 Mon Sep 17 00:00:00 2001 From: Nat Goodspeed Date: Tue, 10 Dec 2019 11:51:38 -0500 Subject: DRTVWR-494: Document LLMainThreadTask class. --- indra/llcommon/llmainthreadtask.h | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'indra/llcommon') 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 // std::result_of #include +/** + * 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 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: -- cgit v1.2.3