Signed arguments in psArray - requested revisions doc

[David.Robbins@…]

The apidelta-report-cycle6 document requested the changing of arguments from
unsigned to signed in the psArray functions list. I have changed these to
unsigned long instead of long. We felt the functionality was better preserved
through keeping these arguments unsigned.
ie.-
spec: psArrayAlloc(long nalloc);
code: psArrayAlloc(psU32 nalloc);

new: psArrayAlloc(unsigned long nalloc);

[Paul Price]

I agree that the prototypes should be:

psArray *psArrayAlloc(unsigned long nalloc);
psArray *psArrayRealloc(psArray *array, unsigned long nalloc);

with:

typedef struct {

const unsigned long n; /< size of array
const unsigned long nalloc; /< allocated data block
psPtr *data; /< pointer to data block
void *lock; /< Optional lock for thread safety

} psArray;

This is in keeping with the policy on allocations that we discussed during the
meeting yesterday.

Any objections?

What about psHashAlloc, psList.size, etc?

[jhoblitt]

There is still the issue of deciding if we're going to check params for
negatives values (I don't know if this was discussed yesterday). RHL was (/is?)
pretty adamant that we do this as general policy... I'm fairly neutral on this
issue so I pretty much changed everything to just long as I'm happy with a
'mere' 63 bits on amd64.

[Paul Price]

I understood that the check would be implemented at the psAlloc level, where the
amount of memory requested would be checked to see if it exceeds a value
specified by the user at compile time.

[jhoblitt]

I think the plan was to add a configurable warning threshold in psAlloc() but I
don't recall that we'd recided to make everything unsigned.

Now that I think about it, there was another reason for sticking with just long.

On several of the containers it would be 'nice' to be able to access elements

from the 'end' of the container. This would require that all
allocators/accessors/mutators are signed or you can imagine someone allocating
more elements then can be accessed.

[Paul Price]

That desirable quality does not affect the allocator --- it just wants a number
of objects, which must be positive.

[jhoblitt]

This is going to be a mouthfull... If the allocator can allocate more objects
then the accessor can access because one is signed and the other is not... there
is going to be some wierd bugs. Isn't it easiest to make them both unsigned?

[Paul Price]

Fair enough.

[jhoblitt]

It's less typing too. :)

[Paul Price]

Gene points out that we need to clarify the decision here.

I think we agreed that we make everything in psArray signed. So, let's do this:

• For the array-ish types (psArray, psVector, psImage), we allow the user to

refer to a negative index to mean address from the end.

• That means that the number of elements in these should be signed --- should be

implemented as ptrdiff_t or similar (ssize_t?)

• It is the responsibility of these structure allocators (e.g., psArrayAlloc) to

check that the requested number of elements is not negative (psAbort otherwise).

• All other allocators simply use size_t where the number of elements is needed

(this saves the trouble of checking before passing to psAlloc).

• psAlloc will check that the requested memory does not exceed a defined limit.

[Paul Price]

Added to the SDRS, just after the section on "APIs for Allocating and Freeing":

\paragraph{Negative allocations}

Note that we have specified that the memory size is unsigned
(\code{size_t}), so that we can address the full range of memory that
the architecture will allow, and to match the behaviour of the system
\code{malloc}. This creates the potential for problems if a negative
value is inadvertently passed to \code{psAlloc} --- it will be
interpreted as a very large positive value. To guard against this, we
specify that \code{psAlloc} must check that the allocation is less
than \code{PS_MEM_LIMIT} (a preprocessor variable).

For array-like collections (specifically, \code{psArray},
\code{psVector}, and \code{psImage}) we allow the user to refer to a
negative index to mean address from the end. Consequently, the number
of elements in structures should be signed. It is the responsibility
of these structure allocators (e.g., \code{psArrayAlloc}) to check
that the requested number of elements is not negative (calling
\code{psAbort} otherwise). All other allocators shall simply use
size_t where the number of elements is needed (saving the trouble of
checking before passing to psAlloc).

[jhoblitt]

I think it would be reasonable to specify ssize_t for the signed types.