In brief, if you call Pike.count_memory(0,x)
you get back
the number of bytes x
occupies in memory.
The detailed story is a bit longer:
This function calculates the number of bytes that all things
occupy. Or put another way, it calculates the number of bytes that
would be freed if all those things would lose their references at
the same time, i.e. not only the memory in the things themselves,
but also in all the things that are directly and indirectly
referenced from those things and not from anywhere else.
The memory counted is only that which is directly occupied by the
things in question, including any overallocation for mappings,
multisets and arrays. Other memory overhead that they give rise to
is not counted. This means that if you would count the memory
occupied by all the pike accessible things you would get a figure
significantly lower than what the OS gives for the pike process.
Also, if you were to actually free the things, you should not
expect the size of the pike process to drop the amount of bytes
returned by this function. That since Pike often retains the
memory to be reused later.
However, what you should expect is that if you actually free the
things and then later allocates some more things for which this
function returns the same size, there should be essentially no
increase in the size of the pike process (some increase might
occur due to internal fragmentation and memory pooling, but it
should be small in general and over time).
The search for things only referenced from things can handle
limited cyclic structures. That is done by doing a "lookahead",
i.e. searching through referenced things that apparently have
other outside references. You can control how long this lookahead
should be through options (see below). If the lookahead is too
short to cover the cycles in a structure then a too low value is
returned. If the lookahead is made gradually longer then the
returned value will eventually become accurate and not increase
anymore. If the lookahead is too long then unnecessary time might
be spent searching through things that really have external
references.
Objects that are known to be part of cyclic structures are
encouraged to have an integer constant or variable
pike_cycle_depth
that specifies the lookahead needed to
discover those cycles. When Pike.count_memory visits such
objects, it uses that as the lookahead when going through the
references emanating from them. Thus, assuming objects adhere to
this convention, you should rarely have to specify a lookahead
higher than zero to this function.
Note that pike_cycle_depth
can also be set to zero to
effectively stop the lookahead from continuing through the object.
That can be useful to put in objects you know have global
references, to speed up the traversal.