Merge pull request #5779 from Rastaban/docs-editor/c26132-1739303621

Create article c26132

Author: AnnaMHuff

docs/code-quality/c26132.md

@@ -0,0 +1,73 @@
+---
+title: Warning C26132
+description: Documentation on static analysis warning C26132
+author:      Rastaban
+ms.author:   philc
+ms.service: visual-cpp
+ms.topic: article
+ms.date:     02/11/2025
+---
+# Warning C26132
+
+> Variable '*variable name*' should be protected by '*lock 1*', but '*lock 2*' is held instead. Possible annotation mismatch.
+
+The analyzer issues Warning C26132 when it detects that a lock, which is annotated to protect a value, isn't held while accessing the value. However, a related lock is held. The code may be thread-safe, so you might need to update the annotations.
+
+This diagnostic usually doesn't indicate a bug in the code, but rather a mismatch between the annotations and the actual locking behavior. If so, the diagnostic should be resolved as there may be other static analysis issues that aren't being reported due to the inconsistent annotations.
+
+## Examples
+
+In the following example, C26132 is emitted when `data` is used.
+
+ The annotation specifies that `customLock01` should protect the variable `data`, but `CustomLockAcquire` is responsible for acquiring the related lock `customLock01->cs`.
+
+```cpp
+#include <sal.h>
+struct CustomLock 
+{
+    int cs; // "Critical Section" lock
+};
+
+_Acquires_exclusive_lock_(criticalSection->cs) // notice the `->` indirection
+void CustomLockAcquire(CustomLock* criticalSection);
+
+_Releases_lock_(criticalSection->cs) // notice the `->` indirection
+void CustomLockRelease(CustomLock* criticalSection);
+
+// global lock
+CustomLock customLock01;
+
+void Initialize(_Guarded_by_(customLock01) int* data)
+{
+    CustomLockAcquire(&customLock01);
+    *data = 1; // C26132
+    CustomLockRelease(&customLock01);
+}
+```
+
+In this example, the `Initialize` function is thread-safe and behaves as designed, but that design isn't correctly reflected in the concurrency SAL annotations. Fix by adjusting the annotations on the custom locking functions to use `criticalSection` rather than `criticalSection->cs`. The warning could also be fixed by changing the `_Guarded_by_` annotation from `customLock01` to `customLock01.cs`.
+
+```cpp
+#include <sal.h>
+struct CustomLock 
+{
+    int cs; // "Critical Section" lock
+};
+
+_Acquires_exclusive_lock_(criticalSection)
+void CustomLockAcquire(CustomLock* criticalSection);
+
+_Releases_lock_(criticalSection)
+void CustomLockRelease(CustomLock* criticalSection);
+
+// global lock
+CustomLock customLock01;
+
+void Initialize(_Guarded_by_(customLock01) int* data)
+{
+    CustomLockAcquire(&customLock01);
+    *data = 1;
+    CustomLockRelease(&customLock01);
+}
+```
+

docs/code-quality/c26133.md

@@ -0,0 +1,76 @@
+---
+title: Warning C26133
+description: Documentation on static analysis warning C26133
+author:      Rastaban
+ms.author:   philc
+ms.service: visual-cpp
+ms.topic: article
+ms.date:     02/19/2025
+---
+# Warning C26133
+
+> Caller failing to hold lock '*lock 1*' before calling function '*function name*', but '*lock 2*' is held instead. Possible annotation mismatch.
+
+Warning C26133 is issued when the analyzer detects that the lock required to call a function isn't held when the function is called. However, another lock that appears to be related is held. It's possible the code is thread-safe, and the annotations need to be updated.
+
+This diagnostic usually doesn't indicate a bug in the code, but rather a mismatch between the annotations and the actual locking behavior. If so, the diagnostic should be resolved as there may be other static analysis issues that aren't being reported due to the inconsistent annotations.
+
+## Examples
+
+In the following example, C26133 is emitted when `DoTaskWithCustomLock` is called.
+
+>  warning C26133: Caller failing to hold lock 'customLock01' before calling function 'DoTaskWithCustomLock', but '(&customLock01)->cs' is held instead. Possible annotation mismatch.
+
+```cpp
+#include <sal.h>
+
+struct CustomLock
+{
+    int cs; // "Critical Section"
+};
+
+_Acquires_exclusive_lock_(criticalSection->cs) // notice the `->` indirection
+void CustomLockAcquire(CustomLock* criticalSection);
+
+_Releases_lock_(criticalSection->cs) // notice the `->` indirection
+void CustomLockRelease(CustomLock* criticalSection);
+
+CustomLock customLock01;
+
+_Requires_lock_held_(customLock01) void DoTaskWithCustomLock();
+
+void DoTask()
+{
+    CustomLockAcquire(&customLock01);
+    DoTaskWithCustomLock(); // C26133
+    CustomLockRelease(&customLock01);
+}
+```
+
+In this example, the `DoTask` function is thread-safe and behaves as designed, but that design isn't correctly reflected in the concurrency SAL annotations. Fix by adjusting the annotations on the custom locking functions to use `criticalSection` rather than `criticalSection->cs`. The warning could also be fixed by changing the `_Requires_lock_held_` annotation from `customLock01` to `customLock01.cs`.
+
+```cpp
+#include <sal.h>
+
+struct CustomLock
+{
+    int cs; // "Critical Section"
+};
+
+_Acquires_exclusive_lock_(criticalSection)
+void CustomLockAcquire(CustomLock* criticalSection);
+
+_Releases_lock_(criticalSection)
+void CustomLockRelease(CustomLock* criticalSection);
+
+CustomLock customLock01;
+
+_Requires_lock_held_(customLock01) void DoTaskWithCustomLock();
+
+void DoTask()
+{
+    CustomLockAcquire(&customLock01);
+    DoTaskWithCustomLock();
+    CustomLockRelease(&customLock01);
+}
+```

docs/code-quality/toc.yml

@@ -591,6 +591,10 @@ items:
     href: ../code-quality/c26117.md
   - name: Warning C26130
     href: ../code-quality/c26130.md
+  - name: Warning C26132
+    href: c26132.md
+  - name: Warning C26133
+    href: c26133.md
   - name: Warning C26135
     href: ../code-quality/c26135.md
   - name: Warning C26138
@@ -634,9 +638,9 @@ items:
   - name: Warning C26831
     href: ../code-quality/c26831.md
   - name: Warning C26838
-    href: c26838.md
+    href: ../code-quality/c26838.md
   - name: Warning C26839
-    href: c26839.md
+    href: ../code-quality/c26839.md
   - name: Warning C26832
     href: ../code-quality/c26832.md
   - name: Warning C26833