Clarify some of the I/O issues.

[openssl.git] / doc / crypto / BIO_should_retry.pod

diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod
index ab67a46114dbaff5df6ab1ce11ca3d5e0ddba55d..6d291b188832b27a375ec2eac20ec8f1db52bd86 100644 (file)
--- a/doc/crypto/BIO_should_retry.pod
+++ b/doc/crypto/BIO_should_retry.pod
@@ -46,7 +46,7 @@ reason other than reading or writing is the cause of the condition.
 BIO_get_retry_reason() returns a mask of the cause of a retry condition
 consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
 B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
 BIO_get_retry_reason() returns a mask of the cause of a retry condition
 consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
 B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of

-these (Q: is this correct?).
+these.

 
 BIO_get_retry_BIO() determines the precise reason for the special
 condition, it returns the BIO that caused this condition and if 
 
 BIO_get_retry_BIO() determines the precise reason for the special
 condition, it returns the BIO that caused this condition and if 


@@ -55,7 +55,7 @@ the reason code and the action that should be taken depends on
 the type of BIO that resulted in this condition.
 
 BIO_get_retry_reason() returns the reason for a special condition if
 the type of BIO that resulted in this condition.
 
 BIO_get_retry_reason() returns the reason for a special condition if

-pass the relevant BIO, for example as returned by BIO_get_retry_BIO().
+passed the relevant BIO, for example as returned by BIO_get_retry_BIO().

 
 =head1 NOTES
 
 
 =head1 NOTES
 


@@ -68,27 +68,17 @@ has reached EOF. Some BIO types may place additional information on
 the error queue. For more details see the individual BIO type manual
 pages.
 
 the error queue. For more details see the individual BIO type manual
 pages.
 

-If the underlying I/O structure is in a blocking mode then most BIO
-types will not signal a retry condition, because the underlying I/O
+If the underlying I/O structure is in a blocking mode almost all current
+BIO types will not request a retry, because the underlying I/O

 calls will not. If the application knows that the BIO type will never
 signal a retry then it need not call BIO_should_retry() after a failed
 BIO I/O call. This is typically done with file BIOs.
 
 calls will not. If the application knows that the BIO type will never
 signal a retry then it need not call BIO_should_retry() after a failed
 BIO I/O call. This is typically done with file BIOs.
 

-The presence of an SSL BIO is an exception to this rule: it can
-request a retry because the handshake process is underway (either
-initially or due to a session renegotiation) even if the underlying
-I/O structure (for example a socket) is in a blocking mode.
-
-The action an application should take after a BIO has signalled that a
-retry is required depends on the BIO that caused the retry.
-
-If the underlying I/O structure is in a blocking mode then the BIO
-call can be retried immediately. That is something like this can be
-done:
-
- do {
-    len = BIO_read(bio, buf, len);
- } while((len <= 0) && BIO_should_retry(bio));
+SSL BIOs are the only current exception to this rule: they can request a
+retry even if the underlying I/O structure is blocking, if a handshake
+occurs during a call to BIO_read(). An application can retry the failed
+call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
+on the underlying SSL structure.

 
 While an application may retry a failed non blocking call immediately
 this is likely to be very inefficient because the call will fail
 
 While an application may retry a failed non blocking call immediately
 this is likely to be very inefficient because the call will fail


@@ -100,18 +90,9 @@ For example if the cause is ultimately a socket and BIO_should_read()
 is true then a call to select() may be made to wait until data is
 available and then retry the BIO operation. By combining the retry
 conditions of several non blocking BIOs in a single select() call
 is true then a call to select() may be made to wait until data is
 available and then retry the BIO operation. By combining the retry
 conditions of several non blocking BIOs in a single select() call

-it is possible to service several BIOs in a single thread. 
-
-The cause of the retry condition may not be the same as the call that
-made it: for example if BIO_write() fails BIO_should_read() can be
-true. One possible reason for this is that an SSL handshake is taking
-place.
-
-Even if data is read from the underlying I/O structure this does not
-imply that the next BIO I/O call will succeed. For example if an
-encryption BIO reads only a fraction of a block it will not be
-able to pass any data to the application until a complete block has
-been read.
+it is possible to service several BIOs in a single thread, though
+the performance may be poor if SSL BIOs are present because long delays
+can occur during the initial handshake process. 

 
 It is possible for a BIO to block indefinitely if the underlying I/O
 structure cannot process or return any data. This depends on the behaviour of
 
 It is possible for a BIO to block indefinitely if the underlying I/O
 structure cannot process or return any data. This depends on the behaviour of