Documentation update, mainly for C API

docs/src/parallel.md

@@ -17,6 +17,9 @@ The maximum value that is advantageous is machine-dependent,
 but it is unlikely to be more than eight due to most computation in 
 HiGHS being memory-bound.
 
+Note that since parallelism is controlled by a static scheduler,
+concurrent Highs instances must use the same value of `threads`.
+
 ## Dual simplex
 
 By default, the HiGHS dual simplex solver runs in serial. However, it

highs/interfaces/highs_c_api.cpp

@@ -164,9 +164,7 @@ HighsInt Highs_qpCall(
 
 void* Highs_create(void) { return new Highs(); }
 
-void Highs_destroy(void* highs) {
-  delete (Highs*)highs;
-}
+void Highs_destroy(void* highs) { delete (Highs*)highs; }
 
 const char* Highs_version(void) { return highsVersion(); }
 HighsInt Highs_versionMajor(void) { return highsVersionMajor(); }

highs/interfaces/highs_c_api.h

@@ -281,15 +281,22 @@ HighsInt Highs_qpCall(
 /**
  * Create a Highs instance and return the reference.
  *
- * Call `Highs_destroy` on the returned reference to clean up allocated memory.
+ * Call `Highs_destroy` on the returned reference to clean up memory
+ * allocated for this instance.
  *
  * @returns A pointer to the Highs instance.
  */
 void* Highs_create(void);
 
 /**
  * Destroy the model `highs` created by `Highs_create` and free all
- * corresponding memory. Future calls using `highs` are not allowed.
+ * memory allocated for this instance. Future calls using `highs` are
+ * not allowed.
+ *
+ * Since the global scheduler's memory is shared by concurrent Highs
+ * instances, it cannot be freed by `Highs_destroy`. Hence, to free
+ * all memory used by HiGHS, `Highs_resetGlobalScheduler` must also be
+ * called.
  *
  * To empty a model without invalidating `highs`, see `Highs_clearModel`.
  *
@@ -2491,6 +2498,12 @@ HighsInt Highs_getIis(void* highs, HighsInt* iis_num_col, HighsInt* iis_num_row,
 /**
  * Releases all resources held by the global scheduler instance.
  *
+ * Although the scheduler instance is created internally by a Highs
+ * instance, any subsequent Highs instances share the
+ * scheduler. Hence, calling `Highs_destroy` does not free the global
+ * scheduler's memory, so `Highs_resetGlobalScheduler` must also be
+ * called.
+ *
  * It is not thread-safe to call this function while calling `Highs_run` or one
  * of the `Highs_XXXcall` methods on any other Highs instance in any thread.
  *