Skip to content

Commit 2621dd1

Browse files
committed
Merge branch 'topic/memory_doc' into 'master'
Add a section about required available memory for "-j" Closes #387 See merge request eng/libadalang/langkit-query-language!334
2 parents 3ee4ec6 + 8bd2f3d commit 2621dd1

File tree

1 file changed

+33
-4
lines changed

1 file changed

+33
-4
lines changed

lkql_checker/doc/gnatcheck_rm/using_gnatcheck.rst

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -109,10 +109,15 @@ The following switches control the general ``gnatcheck`` behavior
109109

110110
``-j``\ nnnn
111111
Use *nnnn* processes to analyze the source files.
112-
On a multi-core machine, this speeds up processing by analyzing subset
113-
of files separately under multiple processes running in parallel.
114-
If ``n`` is 0, then the maximum number processes is the number of
115-
core processors detected on the platform.
112+
On a multi-core machine, this speeds up processing by analyzing subset of
113+
files separately under multiple processes running in parallel. If ``n`` is 0,
114+
then the maximum number processes is the number of core processors detected
115+
on the platform.
116+
117+
.. attention::
118+
119+
Please read the :ref:`Performance_and_Memory` section before using this
120+
flag.
116121

117122
.. index:: -l
118123

@@ -988,6 +993,30 @@ specific version of GNAT, a specific target, or a specific usage profile. Do
988993
not hesitate to contact the AdaCore support if you need help identifying the
989994
entries that may be relevant to you.
990995

996+
.. _Performance_and_Memory:
997+
998+
Performance and Memory Usage
999+
============================
1000+
1001+
GNATcheck performances are closely related to rules you're enabling and to the
1002+
size of the codebase you're running it on, and sometimes it can take a lot of
1003+
time to perform all checks.
1004+
You can use the ``-j`` switch to run GNATcheck in multi-core mode and decrease
1005+
the checking time. However, you have to be careful about memory usage when
1006+
running GNATcheck with this mode enabled:
1007+
1008+
You should count around 3.5 GB of available memory per million source code
1009+
lines, per process. Meaning that for a project with ``l`` source code lines, if
1010+
you run GNATcheck while providing ``n`` as parameter of the ``-j`` switch, you
1011+
will need ``(l / 1,000,000) * 3.5 * n`` GB of available memory (this formula
1012+
isn't valid if ``n = 0``).
1013+
1014+
.. attention::
1015+
1016+
Out-of-memory errors are hard to debug and can lead to system freezes, invalid
1017+
results, or non-deterministic behavior. Thus, make sure you have enough memory
1018+
before running GNATcheck.
1019+
9911020
.. _Transition_from_ASIS-based_GNATcheck:
9921021

9931022
Transition from ASIS-based GNATcheck

0 commit comments

Comments
 (0)