Re: [boost] [context] make_fcontext stack pointer unclear from documentation

Subject: Re: [boost] [context] make_fcontext stack pointer unclear from documentation
From: Michael Marcin (mike.marcin_at_[hidden])
Date: 2013-05-28 12:55:07

On 5/25/2013 2:55 PM, Michael Marcin wrote:
> On 5/25/13 6:03 AM, Oliver Kowalke wrote:
>> 2013/5/25 Michael Marcin <mike.marcin_at_[hidden]>
>>
>>> The function make_fcontext takes a stack pointer. However it is not
>>> clear
>>> at all from the documentation that the stack pointer should actually
>>> point
>>> to the end of the stack buffer.
>>
>>
>> hmm - itis architecture depended in which direction the stack grows. The
>> current supported architectures use downward growing stacks.
>> The documentation contains [1]:
>> 'Note: Depending on the architecture *StackAllocator* returns an address
>> from the top of the stack (grows downwards) or the bottom of the stack
>> (grows upwards). '
>>
>>
>>> [1]
>>> http://www.boost.org/doc/libs/1_53_0/libs/context/doc/html/context/stack.html
>>>
>>>
>
> It's still not clear at all to me after reading that note. And that note
> is far removed from the documentation of make_fcontex which is where
> this matters. Additionally I have to now know how the architecture
> handles stack growth. Shouldn't the library be handling that?
>
> If it's architectures dependent why can't make_fcontext abstract the
> details as it does for other architecture dependent functionality. It
> has all the information necessary to determine if it should offset the
> stack buffer pointer by the stack size.
>
> So instead of:
>
> void* stackBuffer = std::calloc(stackSize, sizeof(char));
> #if TARGET_ARCH_STACK_GROWS_DOWNWARDS
> make_fcontext(static_cast<char*>(stackBuffer)+stackSize, stackSize, f);
> #else
> make_fcontext(stackBuffer, stackSize, f);
> #endif
>
> You could just always write:
> void* stackBuffer = std::calloc(stackSize, sizeof(char));
> make_fcontext(stackBuffer, stackSize, f);
>

I should also note that despite this minor confusion with the stack 
pointer this library is amazing. Great abstraction, simple clean 
interface and just works. It might have taken me a few hours to get it 
working right but it no doubt saved me innumerable hours and saved our 
project's milestone from missing its deadline.

Thank you for your contribution.