1509094 - Add LifoAlloc documentation.

Status: RESOLVED FIXED

(Core :: JavaScript Engine, enhancement, P3)

Description

[Nicolas B. Pierron [:nbp] {back on 17/11}]

Bug 1489572 is changing some of the way LifoAlloc is handling memory, to be used for large allocations too.

We should document how LifoAlloc is structured:
 - 2 list of live chunks, 1 list of unused chunks.
 - What are markers, and where they are used.
 - Why do we have an iterator over LifoAlloc allocations.
 - LifoAllocScope, and how to use them correctly.
 - How to use LifoAlloc as an infallible allocator.
 - Describe the various compilation toggles and memory safety reports instrumentation. (LIFO_CHUNK_PROTECT, LIFO_HAVE_MEM_CHECK, JS_OOM_BREAKPOINT) and induced errors and ways to test and fix them [1].

[1] https://bugzilla.mozilla.org/buglist.cgi?f1=OP&o3=substring&list_id=14442422&short_desc=%5BOOM%5D%20Cannot%20allocate%20a%20new%20chunk&f0=OP&v3=OOM%5D&resolution=FIXED&o2=substring&f4=CP&query_format=advanced&j1=OR&f3=status_whiteboard&f2=short_desc&bug_status=RESOLVED&short_desc_type=allwordssubstr&f5=CP&component=JavaScript%20Engine&component=JavaScript%20Engine%3A%20JIT&component=JavaScript%3A%20GC&component=JavaScript%3A%20Internationalization%20API&component=JavaScript%3A%20Standard%20Library&component=Javascript%3A%20Web%20Assembly&component=js-ctypes&v2=OOM%5D&product=Core

Comment 1

[Nicolas B. Pierron [:nbp] {back on 17/11}]

Attachment: Add LifoAlloc documentation.

This patch add LifoAlloc documentation, to document the main use cases.

This documentation lacks description of LifoAlloc::{steal / transfer*From / free*} functions.

Comment 2

[Matthew Gaudet (he/him) [:mgaudet]]

Comment on attachment 9033332 [details] [diff] [review]
Add LifoAlloc documentation.

Should turn this into a patch and submit :)

Comment 3

[Nicolas B. Pierron [:nbp] {back on 17/11}]

Attachment: Bug 1509094 - Add LifoAlloc documentation.

Comment 4

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/9813615084f6
Add LifoAlloc documentation. r=iain DONTBUILD

Comment 5

[Natalia Csoregi [:nataliaCs]]

https://hg.mozilla.org/mozilla-central/rev/9813615084f6