.. _best-practices-valgrind:

Valgrind
========

``valgrind`` is a tool that can help to check for memory errors.  See
also :ref:`best-practices-sanitizers` for an alternative strategy.

How-to 
------

To run ``valgrind`` on an executable generated by the ``chpl`` compiler:

.. code-block:: bash

     export CHPL_MEM=cstdlib
     export CHPL_TASKS=fifo
     export CHPL_RT_NUM_THREADS_PER_LOCALE=450
     export CHPL_RE2_VALGRIND_SUPPORT=true

     cd $CHPL_HOME
     make
     chpl <program.chpl>
     valgrind ./<program>

This may require clobbering and rebuilding the ``re2`` library:

.. code-block:: bash

     cd $CHPL_HOME/third-party/re2
     make clobber && make

Explanation
-----------

The above options are needed because not all third-party libraries support
``valgrind``. In particular:

- ``jemalloc`` does not support ``valgrind``, which prevents ``valgrind`` from
  accurately tracking allocations/frees
- ``qthreads`` performs task-switching in user-space, so ``valgrind`` is not
  able to keep track of the stack frame correctly
- ``fifo`` needs to limit the number of threads to stay below valgrind's
  ``--max-threads`` default of 500.
- ``re2`` intentionally leaves some memory uninitialized for performance
  reasons, unless ``CHPL_RE2_VALGRIND_SUPPORT=true`` is set at build time
- GASNet support for ``valgrind`` is experimental at this time -- see 
  https://github.com/chapel-lang/chapel/issues/8544 for the current status