7.5.1 Asynchronous operation

GnuTLS can be used with asynchronous socket or event-driven programming. The approach is similar to using Berkeley sockets under such an environment. The blocking, due to network interaction, calls such as gnutls_handshake, gnutls_record_recv, can be set to non-blocking by setting the underlying sockets to non-blocking. If other push and pull functions are setup, then they should behave the same way as recv and send when used in a non-blocking way, i.e., set errno to EAGAIN. Since, during a TLS protocol session GnuTLS does not block except for network interaction, the non blocking EAGAIN errno will be propagated and GnuTLS functions will return the GNUTLS_E_AGAIN error code. Such calls can be resumed the same way as a system call would. The only exception is gnutls_record_send, which if interrupted subsequent calls need not to include the data to be sent (can be called with NULL argument).

The select system call can also be used in combination with the GnuTLS functions. select allows monitoring of sockets and notifies on them being ready for reading or writing data. Note however that this system call cannot notify on data present in GnuTLS read buffers, it is only applicable to the kernel sockets API. Thus if you are using it for reading from a GnuTLS session, make sure that any cached data are read completely. That can be achieved by checking there are no data waiting to be read (using gnutls_record_check_pending), either before the select system call, or after a call to gnutls_record_recv. GnuTLS does not keep a write buffer, thus when writing no additional actions are required.

In the DTLS, however, GnuTLS may block due to retransmission timers required by the protocol. To prevent those timers from blocking a DTLS handshake, the gnutls_init should be called with the GNUTLS_NONBLOCK flag (see Session initialization).

This document was generated on March 23, 2012 using texi2html 5.0.