add discussion and minimal code example for MyPage class.

doc/src/pg_developer.rst

@@ -1108,6 +1108,57 @@ A file that would be parsed by the reader code fragment looks like this:
 Memory pool classes
 ===================
 
+The memory pool classes are used for cases where otherwise many
+small memory allocations would be needed and where the data would
+be either all used or all freed.  One example for that is the
+storage of neighbor lists.  The memory management strategy is
+based on the assumption that allocations will be in chunks of similar
+sizes.  The allocation is then not done per individual call for a
+reserved chunk of memory, but for a "page" that can hold multiple
+chunks of data.  A parameter for the maximum chunk size must be
+provided, as that is used to determine whether a new page of memory
+must be used.
+
+The :cpp:class:`MyPage <LAMMPS_NS::MyPage>` class offers two ways to
+reserve a chunk: 1) with :cpp:func:`get() <LAMMPS_NS::MyPage::get>` the
+chunk size needs to be known in advance, 2) with :cpp:func:`vget()
+<LAMMPS_NS::MyPage::vget>` a pointer to the next chunk is returned, but
+its size is registered later with :cpp:func:`vgot()
+<LAMMPS_NS::MyPage::vgot>`.
+
+.. code-block:: C++
+   :caption: Example of using :cpp:class:`MyPage <LAMMPS_NS::MyPage>`
+
+      #include "my_page.h"
+      using namespace LAMMPS_NS;
+
+      MyPage<double> *dpage = new MyPage<double>;
+      // max size of chunk: 256, size of page: 10240 doubles (=81920 bytes)
+      dpage->init(256,10240);
+
+      double **build_some_lists(int num)
+      {
+          dpage->reset();
+          double **dlist = new double*[num];
+          for (int i=0; i < num; ++i) {
+              double *dptr = dpage.vget();
+              int jnum = 0;
+              for (int j=0; j < jmax; ++j) {
+                  // compute some dvalue for eligible loop index j
+                  dptr[j] = dvalue;
+                  ++jnum;
+              }
+              if (dpage.status() != 0) {
+                  // handle out of memory or jnum too large errors
+              }
+              dpage.vgot(jnum);
+              dlist[i] = dptr;
+          }
+          return dlist;
+      }
+
+----------
+
 .. doxygenclass:: LAMMPS_NS::MyPage
    :project: progguide
    :members:

doc/utils/sphinx-config/false_positives.txt

@@ -1300,6 +1300,7 @@ initializations
 initio
 InP
 inregion
+instantiation
 Institut
 integrators
 Integrators

src/my_page.cpp

@@ -11,36 +11,6 @@
    See the README file in the top-level LAMMPS directory.
 ------------------------------------------------------------------------- */
 
-/* ----------------------------------------------------------------------
-usage:
-  request one datum at a time, repeat, clear
-  request chunks of datums in each get() or vget(), repeat, clear
-  chunk size can vary from request to request
-  chunk size can be known in advance or registered after usage via vgot()
-inputs:
-   template T = one datum, e.g. int, double, struct, int[3]
-     for int[3], access datum as ivec[i][2]
-methods:
-   T *get() = return ptr to one datum
-   T *get(N) = return ptr to N datums, N < maxchunk required
-   T *vget() = return ptr to maxchunk datums, use as needed, then call vgot()
-     all gets return NULL if error encountered
-   vgot(N) = used N datums of previous vget(), N < maxchunk required
-   void init(maxchunk, pagesize, pagedelta)
-     define allocation params and allocate first page(s)
-     call right after constructor
-       can call again to reset allocation params and free previous pages
-     maxchunk = max # of datums in one chunk, default = 1
-     pagesize = # of datums in one page, default = 1024
-       should be big enough to store multiple chunks
-     pagedelta = # of pages to allocate at a time, default = 1
-     return 1 if bad params
-   void reset() = clear pages w/out freeing
-   int size() = return total size of allocated pages in bytes
-   int status() = return error status
-     0 = ok, 1 = chunksize > maxchunk, 2 = allocation error
-------------------------------------------------------------------------- */
-
 #include "my_page.h"
 
 #include <cstdlib>
@@ -77,8 +47,11 @@ using namespace LAMMPS_NS;
  * setting, this determines how often blocks of memory get allocated
  * (fewer allocations will result in faster execution).
  *
- * This class is the "workhorse" for the memory management of
- * neighbor lists. */
+ * \note
+ * This is a template class with explicit instantiation. If the class
+ * is used with a new data type a new explicit instantiation may need to
+ * be added at the end of the file ``src/my_page.cpp`` to avoid symbol
+ * lookup errors. */
 
 /** Create a class instance
  *