Throw an error if a timeout has been exceeded.

Arguments:

session    The clj-libssh2.session.Session object for the current session.
start-time The time the timeout is relative to.
timeout    The number of milliseconds describing the timeout value.

All of the error codes that are documented for libssh2 except for
LIBSSH2_ERROR_SOCKET_NONE which despite its name is a generic error and
LIBSSH2_ERROR_EAGAIN which is almost never actually an error.

These are fallback error messages for when a more appropriate one is not
available from libssh2_session_last_error().

Run some code that might return a negative number to indicate an error.
Raise an exception if this happens.

Arguments:

session A clj-libssh2.session.Session which can be used to generate better
        error messages via session-error-message. This may be nil, in which
        case more generic error messages will be used.

Return:

The return value of the body, *except* in cases where it's a negative number
(but not equal to LIBSSH2_ERROR_EAGAIN). In those cases an exception will be
thrown using maybe-throw-error.

Convert an error return from a native function call into an exception, if
it's warranted.

Arguments:

session    The clj-libssh2.session.Session object for the session where the
           error may have occurred.
error-code An integer return code from a native function.

Return:

Nil if the return code was positive or if the return code was equal to
LIBSSH2_ERROR_EAGAIN. In all other cases an exception is thrown using
ex-info. The message of the exception is the best available message,
preferring the message from session-error-message, falling back to the
matching message in error-messages and finally falling back to a generic
message containing the numeric value of the error. The additional
information map attached using ex-info has the following keys and values
which may be useful to debug the error handling itself:

:error         The error message from error-messages, if any.
:error-code    The numeric return value.
:session       The clj-libssh2.session.Session object, if any.
:session-error The error message from session-error-message, if any.

Log an error and then throw an exception with the same error message and
optionally some additional information.

Arguments:

message          The message to be logged. This will also be the primary
                 message of the exception. If this message is a Throwable,
                 then the additional information will be discarded and the
                 passed-in Throwable will be rethrown after it's logged.
additional-info  A map of additional information which might be useful to
                 anyone debugging an error reported by this exception.

Call libssh2_session_last_error and return the error message given or nil if
there was no error.

Arguments:

session The clj-libssh2.session.Session object for the session where the
        error occurred.

Return:

The message from libssh2_session_last_error or nil if an error message is
available and the provided session was not nil.

Run some code that could return libssh2/ERROR_EAGAIN and if it does, retry
until the timeout is hit. This will *not* interrupt a blocking function as
this is usually used with native functions which probably should not be
interrupted.

N.B. If the function you're calling will block in order to wait on activity
     on the current session's socket, then you should use
     clj-libssh2.socket/block instead as this will select on the socket and
     produce much better retry behaviour.

Arguments:

session The clj-libssh2.session.Session object for the current session.
timeout A number of milliseconds specifying the timeout. This macro will
        wait for at least that number of milliseconds before failing with a
        timeout error. It may return successfully sooner, but this value is
        the minimum time you will wait for failure. The argument can also be
        passed a keyword which will be looked up in the :timeout section of
        the session options.

Return:

Either the return value of the code being wrapped or an exception if the
timeout is exceeded.