GacUI/.github/Guidelines/Coding_MultiThreading.md

Coding Convention (Multi-Threading)

• Most of the code do not require thread safety, DO NOT over engineering.
• SpinLock is only for protecting a piece of code or data in a super flashy short time.
  • When defining a SpinLock field, names it begins with lock, a // covers a, b, c comment is recommended to put above it, a empty line is recommended to put around it.
  • When doing read-process-write but the write part doesn't depend on the result of process:
    • The below rules only involve when process is heavy, if anything is simple, keep it simple.
    • You can copy or move the heavy structure in SPIN_LOCK, and process after SPIN_LOCK.
    • Especially for scenario when a container should be processed and cleared, std::move would be the best choice to copy and clean Vlpp containers. Using moved Vlpp containers is not undefined behavior.
• When using other locks, try your best to only use methods that available to all platforms.
  • Write cross platform code when it is performance optimal for all platforms.
  • If Windows specific methods could make Windows implementation much better, then you are allowed to implement them in different ways.
  • Use lock (both SpinLock and CriticalSection), mutex, semaphore, event, semaphore, rwlock, cv as lock variable prefixes.
• Prefer lock free construction only when the code would be simple, DO NOT involve complex lock free trick unless explicitly required.
• std::atomic<T> should be considered and use it precisely. The code should be correct when running parallelly while I don't want unnecessary std::atomic<T>.
  • atomic_vint is widely used in the library, use it for vint.
• Avoid polling at all cost, I strongly prefer scheduling in async way.

Platform Independence

• Avoid using any platform specific methods.
• ThreadPoolLite::Stop is an exception, if it is used in the application, this function is expected to call at the end of main.

Spawning Threads

vl::Thread class is for heavy resource and time consuming work work:

• Heave time consuming usually means the thread lasts for the lifecycle of the process.
• Inherit from Thread and override Run.
• Avoid using CreateAndStart as your best effort, and strictly avoid in unit test projects, as there are small memory leaks that could pollute the memory leaks detecting.

vl::ThreadPoolLite class is for medium time consuming work:

• Medium time consuming usually means it is spawned to complete a task, and although the task takes time but it is expected to end.
• Avoid using this class too parallelly, it has a limited threads running at the background, queuing too many tasks would cause traffic.

RepeatingTaskExecutor queues inputs to trigger the same task when outdated input is discardable:

• Inherit from RepeatingTaskExecutor and override Execute.
• Calling SubmitTask cause the task to begin:
  • If the previous task is running, the new task would wait, otherwise it starts immediately.
  • If the last submitted task did not start, it is discarded and replaced by the new one, aka the queue only stores one pending task.
• One submission executes the task once, when there is no task running, the system resource will be released.
• One example is editor auto completion with editing text as an input, if the user is typing too fast, outdated queued text is discardable because we only response to the last editor state.

TaskQueue queues multiple tasks to execute in a single thread:

• RunTaskQueue blocks the thread forever until QueueExitTask is called. Before calling QueueExitTask, it blocks even when no task is running.
• QueueExitTask does not cancel any pending QueueTask, all queued task will be executed.

ThreadVariable<T> can be used on global variables, different threads see different copy even when using the same ThreadVariable<T> global variables.