[trafficserver] branch master updated: docs for schedule api

[du...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

duke8253 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new 21dc79a  docs for schedule api
21dc79a is described below

commit 21dc79abb5a5e2a74b47ba4541c761bec372e602
Author: Fei Deng <du...@gmail.com>
AuthorDate: Tue Apr 9 14:59:39 2019 -0500

    docs for schedule api
---
 .../api/functions/TSContScheduleOnPool.en.rst      | 64 ++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/doc/developer-guide/api/functions/TSContScheduleOnPool.en.rst b/doc/developer-guide/api/functions/TSContScheduleOnPool.en.rst
index 462f6a9..f35ddb9 100644
--- a/doc/developer-guide/api/functions/TSContScheduleOnPool.en.rst
+++ b/doc/developer-guide/api/functions/TSContScheduleOnPool.en.rst
@@ -55,6 +55,70 @@ called and continuations that use them have the same restrictions. ``TS_THREAD_P
 are threads that exist to perform long or blocking actions, although sufficiently long operation can
 impact system performance by blocking other continuations on the threads.
 
+Example Scenarios
+=================
+
+Scenario 1 (no thread affinity info, different types of threads)
+----------------------------------------------------------------
+
+When thread affinity is not set, a plugin calls the API on thread "A" (which is an "ET_TASK" type), and
+wants to schedule on an "ET_NET" type thread provided in "tp", the system would see there is no thread
+affinity information stored in "contp."
+
+In this situation, system sees there is no thread affinity information stored in "contp". It then
+checks whether the type of thread "A" is the same as provided in "tp", and sees that "A" is "ET_TASK",
+but "tp" says "ET_NET". So "contp" gets scheduled on the next available "ET_NET" thread provided by a
+round robin list, which we will call thread "B". Since "contp" doesn't have thread affinity information,
+thread "B" will be assigned as the affinity thread for it automatically.
+
+The reason for doing this is most of the time people want to schedule the same things on the same type
+of thread, so logically it is better to default the first thread that it is scheduled on as the affinity
+thread.
+
+Scenario 2 (no thread affinity info, same types of threads)
+-----------------------------------------------------------
+
+Slight variation of scenario 1, instead of scheduling on a "ET_NET" thread, the plugin wants to schedule
+on a "ET_TASK" thread (i.e. "tp" contains "ET_TASK" now), all other conditions stays the same.
+
+This time since the type of the desired thread for scheduling and thread "A" are the same, the system
+schedules "contp" on thread "A", and assigns thread "A" as the affinity thread for "contp".
+
+The reason behind this choice is that we are trying to keep things simple such that lock contention
+problems happens less. And for the most part, there is no point of scheduling the same thing on several
+different threads of the same type, because there is no parallelism between them (a thread will have to
+wait for the previous thread to finish, either because locking or the nature of the job it’s handling is
+serialized since its on the same continuation).
+
+Scenario 3 (has thread affinity info, different types of threads)
+-----------------------------------------------------------------
+
+Slight variation of scenario 1, thread affinity is set for continuation "contp" to thread "A", all other
+conditions stays the same.
+
+In this situation, the system sees that the "tp" has "ET_NET", but the type of thread "A" is "ET_TASK".
+So even though "contp" has an affinity thread, the system will not use that information since the type is
+different, instead it schedules "contp" on the next available "ET_NET" thread provided by a round robin
+list, which we will call thread "B". The difference with scenario 1 is that since thread "A" is set to
+be the affinity thread for "contp" already, the system will NOT overwrite that information with thread "B".
+
+Most of the time, a continuation will be scheduled on one type of threads, and rarely gets scheduled on
+a different type. But when that happens, we want it to return to the thread it was previously on, so it
+won’t have any lock contention problems. And that’s also why "thread_affinity" is not a hashmap of thread
+types and thread pointers.
+
+Scenario 4 (has thread affinity info, same types of threads)
+------------------------------------------------------------
+
+Slight variation of scenario 3, the only difference is "tp" now says "ET_TASK".
+
+This is the easiest scenario since the type of thread "A" and "tp" are the same, so the system schedules
+"contp" on thread "A". And, as discussed, there is really no reason why one may want to schedule
+the same continuation on two different threads of the same type.
+
+.. note:: In scenario 3 & 4, it doesn't matter which thread the plugin is calling the API from.
+
+
 See Also
 ========