n bytes. Storable.

We have two *Bytes types:

• PinnedSizedBytes is backed by pinned ByteArray.
• MLockedSizedBytes is backed by ForeignPtr to mlock-ed memory region.

The ByteString is pinned datatype, but it's represented by ForeignPtr + offset (and size).

I'm sorry for adding more types for bytes. :(

See IsString (PinnedSizedBytes n) instance.

>>> psbToBytes . (id @(PinnedSizedBytes 4)) . psbFromBytes $ [1,2,3,4]
[1,2,3,4]

>>> psbToBytes . (id @(PinnedSizedBytes 4)) . psbFromBytes $ [1,2]
[0,0,1,2]

>>> psbToBytes . (id @(PinnedSizedBytes 4)) . psbFromBytes $ [1,2,3,4,5,6]
[3,4,5,6]

See psbFromBytes.

Convert a ByteString into PinnedSizedBytes. Input should contain the exact number of bytes as expected by type level n size, otherwise error.

Use a PinnedSizedBytes in a setting where its size is 'forgotten' temporarily.

Note

The Ptr given to the function argument must not be used as the result of type r.

As psbUseAsCPtr, but also gives the function argument the size we are allowed to use as a CSize.

This is mostly boilerplate removal, as it is quite common for C APIs to take a combination of a pointer to some data and its length. A possible use case (and one we run into) is where we know that we can expect a certain data length (using PinnedSizedBytes as its representation), but the C API allows any length we like, provided we give the right argument to indicate this. Therefore, having a helper like this one allows us to avoid having to manually natVal a Proxy, as well as ensuring we don't get mismatches accidentally.

The same caveats apply to the use of this function as to the use of psbUseAsCPtr.

As psbUseAsCPtr, but does not 'forget' the size.

The same caveats apply to this use of this function as to the use of psbUseAsCPtr.

As psbCreateResult, but presumes that no useful value is produced: that is, the function argument is run only for its side effects.

As psbCreateResultLen, but presumes that no useful value is produced: that is, the function argument is run only for its side effects.

As psbCreateSizedResult, but presumes that no useful value is produced: that is, the function argument is run only for its side effects.

Given an 'initialization action', which also produces some result, allocate new pinned memory of the specified size, perform the action, then return the result together with the initialized pinned memory (as a PinnedSizedBytes).

Note

It is essential that r is not the Ptr given to the function argument. Returning this Ptr is extremely unsafe:

• It breaks referential transparency guarantees by aliasing supposedly immutable memory; and
• This Ptr could refer to memory which has already been garbage collected, which can lead to segfaults or out-of-bounds reads.

This poses both correctness and security risks, so please don't do it.

As psbCreateResult, but also gives the number of bytes we are allowed to operate on as a CSize.

This function is provided for two reasons:

• It is a common practice in C libraries to pass a pointer to data plus a length. While our use case might know the size we expect, the C function we are calling might be more general. This simplifies calling such functions.
• We avoid natValing a Proxy twice, since we have to do it anyway.

The same caveats apply to this function as to psbCreateResult: the Ptr given to the function argument must not be returned as r.

As psbCreateResult, but gives a SizedPtr to the function argument. The same caveats apply to this function as to psbCreateResult: the SizedPtr given to the function argument must not be resulted as r.