Re: cbdata branch

On Fri, Jan 05, 2001, Robert Collins wrote:
> Perhaps a little doco on the changes?

Pasted straight from the programmers guide, which was already
reasonably up to date .. :)

Moez took the cbdata code and made a cbdata entity have a
mempool entity. This saves having to do all those hash
operations, but it *does* mean corrupt memory can trigger even
stranger bugs. Hopefully corrupted memory can be nabbed by the
"cookie" used (each cbdata "header" has a pointer field pointing
to itself, which is used for consistency checking to make sure the
given cbdata is actually a valid cbdata..)

        <P>
        The callback data allocator lets us do this in a uniform and
        safe manner. The callback data allocator is used to allocate,
        track and free memory pool objects used during callback
        operations. Allocated memory is locked while the blocking
        operation executes elsewhere, and is freed when the operation
        completes. The normal sequence of events is:
<verb>
        callback_data = CBDATA_ALLOC(type_of_data, free_handler);
        ...
        cbdataLock(callback_data);
        fooOperationStart(bar, callback_func, callback_data);
        ...
        fooOperationComplete(...);
        if (cbdataValid(callback_data)) {
                callback_func(callback_data, ....);
        cbdataUnlock(callback_data);
        cbdataFree(callback_data);
</verb>
           
        <P>
        With this scheme, nothing bad happens if <tt/cbdataFree/ gets called
        before <tt/cbdataUnlock/:
<verb>
        callback_data = CBDATA_ALLOC(...);
        ...
        cbdataLock(callback_data);
        fooOperationStart(bar, callback_func, callback_data);
        ...
        cbdataFree(callback_data);
        ...
        fooOperationComplete(...);
        if (cbdataValid(callback_data)) {
                callback_func(callback_data, ....);
        cbdataUnlock(callback_data);
</verb>
        In this case, when <tt/cbdataFree/ is called before
        <tt/cbdataUnlock/, the callback_data gets marked as invalid. Before
        executing the callback function, <tt/cbdataValid/ will return 0
        and callback_func is never executed. When <tt/cbdataUnlock/ gets
        called, it notices that the callback_data is invalid and will
        then call <tt/cbdataFree/.
        

-- 
Adrian Chadd			"Here's five for the cake, and
<adrian@creative.net.au>	  five to buy a clue."
				    - Ryan, Whatever it Takes