Timon Gehr , dans le message (digitalmars.D:144140), a écrit : > Well, I don't really want dangerously looking stuff in my codebase, but > I definitely am going to use the region allocator. BTW invalidatingCopy > is a bad name because: > > 1. nothing is invalidated, the other allocators are just 'suspended'. > 2. nothing is copied, the result is a new region allocator. > > It is just like a function that is lower on the call stack cannot make > any stack allocations until the function it has called returns.
I prefer to see dangerously looking stuff in the code when one is performing dangerously looking operations. invalidatingCopy may not be the right name. suspendingCopy of exclusiveCopy are already two better names. The point is to give an better name than "RegionAllocator that share a common RegionAllocatorStack (but are not direct copies of the RegionAllocator)". > This is biased in that it assumes that the documentation will magically > be more understandable if the API changes from a (imo) comprehensive and > powerful one to a dangerously-looking one. Giving a name to stuff, so that the user is always refered to the same point in the documentation that you take particularly care to make understandable, makes the documentation more understandable than spread documentation. It's not magic. After more thoughts, this can be achieve by keeping the RegionAllocatorStack semantic: auto stack = RegionAllocatorStack(...); // or RegionAllocator.Stack() or std.region_allocator.Stack() auto alloc = stack.instanciateAllocator(); The documentation is improved so that instanciateAllocator gives information about stack sharing and suspension of previous allocators. Now, in allocate(), free(), etc, the documentation refer to "RegionAllocators that were instanciated from the same Stack". Now you have a name that refers to instanciateAllocator. This can be another name, but not newRegionAllocator. I though about instanciate because the documentation reads for example in allocate: | The last block allocated from this RegionAllocator instance can be | freed by calling RegionAllocator.free or RegionAllocator.freeLast or | will be automatically freed when the last copy of this RegionAllocator | instance goes out of scope. Here the word "instance" is used, but is not defined. The user may think that a new instance is created when a simple copy of the RegionAllocator is performed, which is perfectly true, but do not apply to what is meant in this documentation. If the user was made to type instanciateAllocator, he could no longer say he had no idea what the word "instance" could mean in the documentation. newAllocator does not fulfill this. In the end you are right, the confusion does not comes from the Stack semantics, it comes from the fact that newRegionAllocator is not documented at all, and has a confusing name. > I do not think an user who does not understand the region allocator will > make effective use of it anyways. He will be able to optimize code when a stack allocator is better, even if he does not know about the possibility to create a new allocator from the same stack. > Creating a new RegionAlloc is not free. I don't want overhead for stuff > I don't need. Well, it's not free, but its rather cheap. You will not create RegionAllocatorStack only once in a while. Actually, you want to create a stack only once per thread. And this stack is created in a library function in which you can avoid to create the expensive RegionAllocator. > Again, making the stack semantics obscure by trying to not show it to > the user as good as possible is not going to help anyone understanding > the stack semantics. Ok, that's a point. That should not prevent the RegionAllocator to give a way to instanciate another RegionAllocator from the same stack, which is more powerful than having to carry an extra copy of the RegionAllocatorStack, even it requires calling myAlloc.stack.instanciateAllocator().
