2.4. Data flow buffering

All data transfer functions make use of the internal per-connection buffer to optimize performance and prevent the application from implementing its own complicated memory management. The incoming data flow is accumulated in the incoming buffer and can be partially or fully reterived using functions rascal_read and rascal_reads. The rascal_reads function was designed to simplify working with text based protocols, such as SMTP or IRC: it retrieves a single line of text from the head of the FIFO buffer.

The output function, rascal_write, appends the data to the output buffer of a connection.

Note that all transfer functions copy the data either to or from the internal buffer. There are no functions to receive data directly into user defined area of memory or to send from there.

Note also that the data is sent and received by portions, each several kilobytes in size. Keep this in mind when reading large amounts of data of a known size, for which you can allocate enough memory. Also keep that in mind when writing large amounts of data that you anyway keep in memory. The size of the internal cache is not limited, but frequent expansion can lead to poor performance and inoptimal resource usage; it is preferred that the application sends each portion of data as soon as a rop_write event is reported (see below).