add discussion and minimal code example for MyPage class.

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:

initio

InP

inregion

instantiation

Institut

integrators

Integrators

   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>

 * 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

 *