Merge pull request #11710 from geoffw0/qldocalloc

C++: Clarify Allocation.qll and Deallocation.qll

cpp/ql/lib/semmle/code/cpp/models/interfaces/Allocation.qll

@@ -11,38 +11,6 @@
 import semmle.code.cpp.Function
 import semmle.code.cpp.models.Models
 
-/**
- * An allocation function such as `malloc`.
- */
-abstract class AllocationFunction extends Function {
-  /**
-   * Gets the index of the argument for the allocation size, if any. The actual
-   * allocation size is the value of this argument multiplied by the result of
-   * `getSizeMult()`, in bytes.
-   */
-  int getSizeArg() { none() }
-
-  /**
-   * Gets the index of an argument that multiplies the allocation size given by
-   * `getSizeArg`, if any.
-   */
-  int getSizeMult() { none() }
-
-  /**
-   * Gets the index of the input pointer argument to be reallocated, if this
-   * is a `realloc` function.
-   */
-  int getReallocPtrArg() { none() }
-
-  /**
-   * Whether or not this allocation requires a corresponding deallocation of
-   * some sort (most do, but `alloca` for example does not).  If it is unclear,
-   * we default to no (for example a placement `new` allocation may or may not
-   * require a corresponding `delete`).
-   */
-  predicate requiresDealloc() { any() }
-}
-
 /**
  * An allocation expression such as call to `malloc` or a `new` expression.
  */
@@ -86,6 +54,41 @@ abstract class AllocationExpr extends Expr {
   predicate requiresDealloc() { any() }
 }
 
+/**
+ * An allocation function such as `malloc`.
+ *
+ * Note: `AllocationExpr` includes calls to allocation functions, so prefer
+ * to use that class unless you specifically need to reason about functions.
+ */
+abstract class AllocationFunction extends Function {
+  /**
+   * Gets the index of the argument for the allocation size, if any. The actual
+   * allocation size is the value of this argument multiplied by the result of
+   * `getSizeMult()`, in bytes.
+   */
+  int getSizeArg() { none() }
+
+  /**
+   * Gets the index of an argument that multiplies the allocation size given by
+   * `getSizeArg`, if any.
+   */
+  int getSizeMult() { none() }
+
+  /**
+   * Gets the index of the input pointer argument to be reallocated, if this
+   * is a `realloc` function.
+   */
+  int getReallocPtrArg() { none() }
+
+  /**
+   * Whether or not this allocation requires a corresponding deallocation of
+   * some sort (most do, but `alloca` for example does not).  If it is unclear,
+   * we default to no (for example a placement `new` allocation may or may not
+   * require a corresponding `delete`).
+   */
+  predicate requiresDealloc() { any() }
+}
+
 /**
  * An `operator new` or `operator new[]` function that may be associated with
  * `new` or `new[]` expressions.  Note that `new` and `new[]` are not function

cpp/ql/lib/semmle/code/cpp/models/interfaces/Deallocation.qll

@@ -11,16 +11,6 @@
 import semmle.code.cpp.Function
 import semmle.code.cpp.models.Models
 
-/**
- * A deallocation function such as `free`.
- */
-abstract class DeallocationFunction extends Function {
-  /**
-   * Gets the index of the argument that is freed by this function.
-   */
-  int getFreedArg() { none() }
-}
-
 /**
  * An deallocation expression such as call to `free` or a `delete` expression.
  */
@@ -31,6 +21,19 @@ abstract class DeallocationExpr extends Expr {
   Expr getFreedExpr() { none() }
 }
 
+/**
+ * A deallocation function such as `free`.
+ *
+ * Note: `DeallocationExpr` includes calls to deallocation functions, so prefer
+ * to use that class unless you specifically need to reason about functions.
+ */
+abstract class DeallocationFunction extends Function {
+  /**
+   * Gets the index of the argument that is freed by this function.
+   */
+  int getFreedArg() { none() }
+}
+
 /**
  * An `operator delete` or `operator delete[]` function that may be associated
  * with `delete` or `delete[]` expressions.  Note that `delete` and `delete[]`