Restructure pointer/threading docs and add lock-free DS reference

Multithreading doc rewritten with numbered headings (1, 1.1, ...),
runnable examples, and new sections covering std::jthread/std::stop_token,
expanded semaphores, spurious wakeups, std::atomic with memory ordering,
and the ABA problem. Producer-consumer example simplified.

Pointer docs split:
- pointers.md: trimmed to raw pointers, dangling/wild, ASan
- smart_pointers.md (new): unique/shared/weak, custom deleters,
  enable_shared_from_this, atomic smart pointers
- shared_ptr_use_cases.md (new): 12 patterns where shared ownership
  is the right tool, with minimal code each
- references.md (new): refs, lvalue/rvalue, reference_wrapper, ref/cref
- passing_returning: renumbered, added const shared_ptr<T>& form,
  enable_shared_from_this guidance
- smart_pointers_class_member: PIMPL idiom, polymorphic ownership,
  Rule of Zero, thread-safety pointer-vs-pointee distinction

New docs/lock_free_data_structures.md covering SPSC ring buffer,
SPSC unbounded queue, MPSC (Vyukov intrusive), SPMC (Chase-Lev),
MPMC (Vyukov bounded), hazard pointers + Treiber stack, and
epoch-based reclamation, with full implementations.

README updated: pointer docs split into separate entries; broken
multithreading anchors fixed to numbered sections; lock-free docs
listed under C++ System Design.

clang_format.sh removed; clang-format is now driven from CMakeLists.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: behnamasadi

README.md

@@ -212,9 +212,12 @@ This change ensures that VSCode uses the "Ninja Multi-Config" generator by defau
 - [Register Keyword](docs/register.md)
 - [Regex](docs/regex.md)
 - [Pseudo-random Number Generation, Distributions](docs/random_number.md)
-- [Raw Pointers, Smart (Shared, Unique, Weak) Pointers, Reference, addressof, reference_wrapper, std::ref](docs/pointers.md)
+- [Raw Pointers, Wild/Dangling, Memory Safety](docs/pointers.md)
+- [Smart Pointers (unique_ptr, shared_ptr, weak_ptr, atomic smart pointers)](docs/smart_pointers.md)
+- [When to Use shared_ptr — 12 Concrete Patterns](docs/shared_ptr_use_cases.md)
 - [Passing/ Returning Smart Pointers To/ From Functions](docs/passing_returning_smart_pointers_to_from_functions.md)
 - [Smart Pointers Class Member](docs/smart_pointers_class_member.md)
+- [References, Lvalue/Rvalue, reference_wrapper, std::ref / std::cref](docs/references.md)
 - [Return, Abort, Exit, Throw, Terminate](docs/return_abort_exit_throw_terminate.md)
 - [Scope Resolution Operator](docs/scope_resolution_operator.md)
 - [Scope and Life Cycle of Objects Returned by Functions](docs/scope_and_life_cycle_of_objects_returned_by_functions.md)
@@ -269,26 +272,22 @@ This change ensures that VSCode uses the "Ninja Multi-Config" generator by defau
   - [Virtual Function Abstract Class](docs/virtual_function_abstract_class.md)
   - [Virtual Destructor, Virtual Constructor](docs/virtual_destructor_virtual_constructor.md)
 * [Multithreading and Process](#)
-  - [Process, Inter Process Communication (IPC), Process Tree, Process Control Block (PCB](docs/process.md)
-  - [Creating (Thread Callable Objects), Terminating Threads](docs/multithreading.md#creation_and_termination)
-  - [Over Subscription](docs/multithreading.md#over_subscrition)
-  - [Differentiating Between Threads](docs/multithreading.md#differentiating_between_threads)
-  - [Sleeping Threads](docs/multithreading.md#sleeping_threads)
-  - [Joining/ Detaching Threads, Joinable Detachable](docs/multithreading.md#join_detach_threads)
-  - [Threads Yield](docs/multithreading.md#yield)
-  - [Thread Synchronization](docs/multithreading.md#thread_synchronization)
-  - [Racing Condition](docs/multithreading.md#racing_condition)
-  - [Mutex](docs/multithreading.md#mutex)
-  - [Semaphor](docs/multithreading.md#semaphor)
-  - [Thread Safe](docs/multithreading.md#thread_safe)
-  - [Dead Lock](docs/multithreading.md#dead_lock)
-  - [Lock Guard](docs/multithreading.md#lock_guard)
-  - [Scoped Lock](docs/multithreading.md#scoped_lock)
-  - [Unique Lock](docs/multithreading.md#unique_lock)
-  - [Condition Variable](docs/multithreading.md#condition_variable)
-  - [Future, Promise and async](docs/multithreading.md#async_future_promise)
-  - [Packaged Task](docs/multithreading.md#packaged_task)
-  - [Event handling/ Concurrency/ Thread design pattern](docs/thread_design_pattern.md)
+  - [Process, Inter Process Communication (IPC), Process Tree, Process Control Block (PCB)](docs/process.md)
+  - [Multithreading — Overview](docs/multithreading.md#1-overview)
+  - [Creating and Terminating Threads (function pointer, member function, functor, lambda)](docs/multithreading.md#2-creating-and-terminating-threads)
+  - [Joining and Detaching Threads](docs/multithreading.md#27-joining-threads)
+  - [std::jthread and std::stop_token (C++20)](docs/multithreading.md#29-stdjthread-c20)
+  - [Hardware Concurrency and Oversubscription](docs/multithreading.md#32-hardware-concurrency-and-oversubscription)
+  - [Thread Identity, Sleeping, Yielding](docs/multithreading.md#3-thread-properties)
+  - [Race Conditions vs Data Races](docs/multithreading.md#411-race-condition-vs-data-race)
+  - [Mutex (std::scoped_lock, lock_guard, unique_lock)](docs/multithreading.md#42-mutex)
+  - [Deadlock and How to Avoid It](docs/multithreading.md#423-deadlock)
+  - [Semaphores (counting, binary)](docs/multithreading.md#43-semaphores)
+  - [Condition Variables and Spurious Wakeups](docs/multithreading.md#44-condition-variables)
+  - [std::future, std::async, std::promise, std::packaged_task](docs/multithreading.md#5-async-tasks-and-stdfuture)
+  - [std::atomic, Memory Ordering, ABA Problem](docs/multithreading.md#6-stdatomic)
+  - [Designing Thread-Safe Classes](docs/multithreading.md#7-designing-thread-safe-classes)
+  - [Event handling / Concurrency / Thread Design Patterns](docs/thread_design_pattern.md)
 
 ## [Advance C++ Concepts and Idioms](#)
 
@@ -395,7 +394,7 @@ This change ensures that VSCode uses the "Ninja Multi-Config" generator by defau
 - [Memory Management Strategies (Pool, Arena, Slab Allocators)](docs/system_design/memory_management.md)
 - [Object-Oriented Design Patterns (Factory, Singleton, Observer, Strategy)](docs/system_design/design_patterns.md)
 - [Concurrency Patterns (Thread Pool, Producer-Consumer, Active Object)](docs/system_design/concurrency_patterns.md)
-- [Lock-Free and Wait-Free Data Structures](docs/system_design/lock_free_structures.md)
+- [Lock-Free Data Structures (SPSC/SPMC/MPMC, ring buffers, hazard pointers, RCU)](docs/lock_free_data_structures.md)
 - [Cache-Friendly Data Structures and Data-Oriented Design](docs/system_design/cache_friendly_design.md)
 - [Plugin Architecture and Dynamic Loading](docs/system_design/plugin_architecture.md)
 - [Event-Driven Architecture and State Machines](docs/system_design/event_driven_state_machines.md)