diff options
| author | Hugo Landau <hlandau@openssl.org> | 2023-08-22 16:59:57 +0100 |
|---|---|---|
| committer | Tomas Mraz <tomas@openssl.org> | 2023-08-25 15:10:43 +0200 |
| commit | 9d6bd3d30f8068a5558efa0bda2db570500ff364 (patch) | |
| tree | ae0a2678ddc64bafac019e3c48e42a34deb636bf /doc | |
| parent | 10536b7f5b07aab3dc9631e94a56258155a1d942 (diff) | |
| download | openssl-9d6bd3d30f8068a5558efa0bda2db570500ff364.tar.gz | |
QUIC APL: Implement backpressure on stream creation
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21811)
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man3/SSL_new_stream.pod | 28 |
1 files changed, 26 insertions, 2 deletions
diff --git a/doc/man3/SSL_new_stream.pod b/doc/man3/SSL_new_stream.pod index 7888cc4490..a3ca2b96a9 100644 --- a/doc/man3/SSL_new_stream.pod +++ b/doc/man3/SSL_new_stream.pod @@ -2,13 +2,16 @@ =head1 NAME -SSL_new_stream, SSL_STREAM_FLAG_UNI - create a new locally-initiated QUIC stream +SSL_new_stream, SSL_STREAM_FLAG_UNI, SSL_STREAM_FLAG_NO_BLOCK, +SSL_STREAM_FLAG_ADVANCE - create a new locally-initiated QUIC stream =head1 SYNOPSIS #include <openssl/ssl.h> - #define SSL_STREAM_FLAG_UNI (1U << 0) + #define SSL_STREAM_FLAG_UNI (1U << 0) + #define SSL_STREAM_FLAG_NO_BLOCK (1U << 1) + #define SSL_STREAM_FLAG_ADVANCE (1U << 2) SSL *SSL_new_stream(SSL *ssl, uint64_t flags); =head1 DESCRIPTION @@ -38,6 +41,27 @@ L<SSL_accept_stream(3)>. Calling SSL_new_stream() if there is no default stream already present inhibits the future creation of a default stream. See L<openssl-quic(7)>. +The creation of new streams is subject to flow control by the QUIC protocol. If +it is currently not possible to create a new locally initiated stream of the +specified type, a call to SSL_new_stream() will either block (if the connection +is configured in blocking mode) until a new stream can be created, or otherwise +return NULL. + +This function operates in blocking mode if the QUIC connection SSL object is +configured in blocking mode (see L<SSL_set_blocking_mode(3)>). It may also be +used in nonblocking mode on a connection configured in blocking mode by passing +the flag B<SSL_STREAM_FLAG_NO_BLOCK>. + +The flag B<SSL_STREAM_FLAG_ADVANCE> may be used to create a QUIC stream SSL +object even if a new QUIC stream cannot yet be opened due to flow control. The +caller may begin to use the new stream and fill the write buffer of the stream +by calling L<SSL_write(3)>. However, no actual stream data (or QUIC frames +regarding the stream) will be sent until QUIC flow control allows it. Any queued +data will be sent as soon as a peer permits it. There is no guarantee the stream +will be eventually created; for example, the connection could fail, or a peer +might simply decide never to increase the number of allowed streams for the +remainder of the connection lifetime. + =head1 RETURN VALUES SSL_new_stream() returns a new stream object, or NULL on error. |