1. The last part of the module description [lines 57-59 in the source]
is a little hard to follow.
2. The description of out of memory behaviour in the ddoc for
RegionAllocatorException [100-104] should be just one sentence, not two.
3. There is too much whitespace between the values of the GCScan enum ^^
4. I think there is a comma missing (or something) from the first XREF
in the description of RegionAllocatorStack [131]
5. In the example for RegionAllocatorStack [152-174], I suspect it might
be easier to follow if there were a comment highlighting that fun1
passes stack to fun2.
NB I also keep getting muddled between RegionAllocator and
RegionAllocatorStack, as if my brain only differentiates identifiers by
the first 15 characters, probably more an issue with me than the module ^^
6. ddoc for RegionAllocatorStack's constructor [84-186] should mention
that it throws when passed 0 as the segment size.
7. docs for scanThreadLocalStack is vague about exception type (source
on git hub appears to be correct, so I'll assume they are just out of
sync, from here on I'll review the ddoc straight from the source).
8. examples for struct RegionAllocator [448-508] Is it possible to split
this into 2 or 3 sub examples, to make it more clear that foo and bar
are interdependent, but independent from the rest?
9. Note about large allocations [512-520] the last sentence about time
considerations is a little clumsy, don't be afraid to to use big-O
notation to make it clear what effects what.
10. resize [825...] Not sure if I like it returning a bool to denote
success/failure, I think I'd prefer it to throw if the resize fails.
11. uninitializedArray [909...] ddoc seems a bit misleading, should
perhaps be something like...
"Same as newArray, except skips initialization of elements for
occasions when greater performance is required."
12. alignBytes [939...] just has me stumped, the introduction says that
16 byte alignment is guaranteed, so shouldn't this always return 16? I
tried to follow the breadcrumbs through the source, but couldn't find
where the value it returns is defined, only places where it is used/checked.
13. array [990...] I think this needs a more elaborate example that
shows a full use case. Also, what happens if it is passed an infinite range?
And your GCAllocator bonus
14. The macro for array [137] is incomplete so nothing shows up in the
ddoc output.
On the whole I think this module goes way over my head! I think some of
my confusion originates from the naming of RegionAllocatorStack which,
if I'm finally up to speed, is not a stack of RegionAllocators, but the
actual stack which is being allocated from, in segments. I can
understand why the module is not named SegmentAllocator, but nowhere is
the term Region explained.
Is the restriction that only the most recently created RegionAllocator
(for a given stack) can be used going to be universal across all
allocator implementations? It doesn't seem to be the case for the
GCAllocator, which makes me worry that some (future) Allocators will not
be interchangeable, even though they share the same API. That being
said, the only problematic scenarios that I can think of are rather
contrived.
I hope some of that made sense, I suspect much of it may not ><
A...
