[cairo] SUMMARY of Implementing cairo_read_func_t/cairo_write_func_t properly

[Bernhard R. Fischer]

On 2016-01-05 08:12, Bernhard Fischer wrote:
> On Monday 04 January 2016 18:26:28 Behdad Esfahbod wrote:
>> On 16-01-04 06:24 PM, Bill Spitzak wrote:
>>> On Sun, Jan 3, 2016 at 11:50 PM, Bernhard Fischer <bf at abenteuerland.at
>>>
>>> <mailto:bf at abenteuerland.at>> wrote:
>>>     On Sunday 03 January 2016 14:29:57 Behdad Esfahbod wrote:
>>>     > On 16-01-02 09:34 PM, Bill Spitzak wrote:
>>>     > > On 01/02/2016 01:27 PM, Bernhard Fischer wrote:
>>>     > >> On Saturday 02 January 2016 13:01:39 Bill Spitzak wrote:
>>>     > >>> I think the api has to be changed to return number of bytes
>>>     > >>> read, and a
>>>     > >>> negative number for eof.
>>>     > >> 
>>>     > >> The return value should be the number of bytes read and on eof it
>>>     > >> is
>>>     > >> something between 0 and length. If it is called again at/after
>>>     > >> eof it
>>>     > >> returns 0 again. A negative value (-1) is only returned in case
>>>     > >> of error
>>>     > >> (but not EOF). This is exactly like read(3) behaves.
>>>     > > 
>>>     > > Yes you are correct, I made a typo, I meant to say "error" where I
>>>     > > wrote
>>>     > > "eof". I fully agree with your description.
>>>     > 
>>>     > Given that we cannot change the signature now, I suggest we hack it
>>>     > up to
>>>     > interpret negative numbers returned from the callback to be
>>>     > interpreted as a short read; the absolute value of the returned
>>>     > negative number is the number of bytes read.
>>>     > 
>>>     > Cairo itself won't need to be updated, but clients should be
>>>     > encouraged to
>>>     > implement the new behaviour.
>>>     > 
>>>     > b
>>>     
>>>     I agree, that is a backwards compatible solution.
>>>
>>> I think you need to make negative number mean "it was this short". Ie if a
>>> request to read 10 bytes only reads 8, it returns -2.
>>>
>>> The reason is so that reading the entire block still returns
>>> CAIRO_STATUS_SUCCESS.
>> That works as well.  I was thinking, negative number returned only if not a
>> full read.
> 
> 
> I have a new idea to stay backwards compatible:
> The read function shall return the negative number of bytes which have NOT 
> been read, i.e. - (length - bytes_read).
> 
> This is that a full read will return 0 which is CAIRO_STATUS_SUCCESS.
> Truncated reads return something between -1 and -length.
> And on error, of course CAIRO_READ_ERROR is returned.
> 
> 
> Bernhard
> 


The conclusion of this discussion was to slightly adapt the meaning of
the return value of the read_func_t as follows:


The read function shall return the negative number of bytes which have
NOT been read, i.e. - (length - bytes_read).
This is that a full read will return 0 which is CAIRO_STATUS_SUCCESS.
Truncated reads return something between -1 and -length. On error,
CAIRO_STATUS_READ_ERROR is returned (which is a positive value).



If there is the consent of the core devs we should adapt the docs.

I'll have a look at cairo_image_surface_create_from_png_stream() if
there is a change necessary.

Bernhard