perlapi: Combine Poison() and PoisonFree() entries

[khwilliamson]

[jkeenan]

@khwilliamson, when I build this branch and call perldoc pod/perlapi.pod, I get:

    "PoisonFree"
    "Poison"
        These each call PoisonWith(0xEF) for catching access to freed
        memory.

            void  PoisonFree(void* dest, int nitems, type)
            void  Poison    (void* dest, int nitems, type)

    "PoisonNew"
        PoisonWith(0xAB) for catching access to allocated but uninitialized
        memory.

            void  PoisonNew(void* dest, int nitems, type)

    "PoisonWith"
        Fill up memory with a byte pattern (a byte repeated over and over
        again) that hopefully catches attempts to access uninitialized
        memory.

            void  PoisonWith(void* dest, int nitems, type, U8 byte)

I.e., 3 entries for 4 API calls. Based on all the other p.r.s you've created lately, I would have expected you to combine these into just 1 entry. (They are 4 separate entries in blead.) Was there some reason you could not or chose not to do so in this case? Thanks.

[khwilliamson]

I hadn't thought about it. I will now think about the advisability

[tonycoz]

I.e., 3 entries for 4 API calls. Based on all the other p.r.s you've created lately, I would have expected you to combine these into just 1 entry.

The two that have been combined do exactly the same thing - poison memory that is about to be freed.

The PoisonNew() is similar, but it has a different purpose - poison memory that has just been allocated to ensure that it is properly initialized in the future (though it will confuse valgrind's initialized memory tracking, yay).

PoisonWith() is the tool the others use to do their jobs.

I'd tend away from combining PoisonNew() and PoisonWith() into the others, since their purposes are different.