<html><!-- Created using the cpp_pretty_printer from the dlib C++ library.  See http://dlib.net for updates. --><head><title>dlib C++ Library - timeout_abstract.h</title></head><body bgcolor='white'><pre>
<font color='#009900'>// Copyright (C) 2007  Davis E. King (davis@dlib.net)
</font><font color='#009900'>// License: Boost Software License   See LICENSE.txt for the full license.
</font><font color='#0000FF'>#undef</font> DLIB_TIMEOUT_KERNEl_ABSTRACT_
<font color='#0000FF'>#ifdef</font> DLIB_TIMEOUT_KERNEl_ABSTRACT_

<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../threads.h.html'>../threads.h</a>"

<font color='#0000FF'>namespace</font> dlib
<b>{</b>

    <font color='#0000FF'>class</font> <b><a name='timeout'></a>timeout</b> 
    <b>{</b>
        <font color='#009900'>/*!
            WHAT THIS OBJECT REPRESENTS
                This object provides a simple way to implement a timeout.  An example will
                make its use clear.  Suppose we want to read from a socket but we want to
                terminate the connection if the read takes longer than 10 seconds.  This
                could be accomplished as follows:

                connection* con = a connection from somewhere;
                {
                    // setup a timer that will call con-&gt;shutdown() in 10 seconds
                    timeout t(*con,&amp;connection::shutdown,10000); 
                    // Now call read on the connection.  If this call to read() takes more
                    // than 10 seconds then the t timeout will trigger and shutdown the
                    // connection.  If read completes in less than 10 seconds then the t
                    // object will be destructed on the next line due to the } and then the
                    // timeout won't trigger.
                    con-&gt;read(buf,100);
                }

                
                Alternatively, if you have a compiler capable of using C++11 lambda
                functions, you can use a syntax like this:
                {
                    timeout t([con](){ con-&gt;shutdown(); }, 10000);
                    con-&gt;read(buf,100);
                }

                More generally, you can use this with things other than sockets.  For
                example, the following statement will print "Hello world!" after 1000ms:
                    timeout t([](){ cout &lt;&lt; "Hello world!" &lt;&lt; endl; },  1000);



            THREAD SAFETY
                All methods of this class are thread safe. 
        !*/</font>

    <font color='#0000FF'>public</font>:

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> T
            <font color='#5555FF'>&gt;</font>
        <b><a name='timeout'></a>timeout</b> <font face='Lucida Console'>(</font>
            T callback_function,
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> ms_to_timeout
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - callback_function does not throw
            ensures                
                - does not block.
                - #*this is properly initialized
                - if (this object isn't destructed in ms_to_timeout milliseconds) then
                    - callback_function() will be called in ms_to_timeout milliseconds.
            throws
                - std::bad_alloc
                - dlib::thread_error
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> T
            <font color='#5555FF'>&gt;</font>
        <b><a name='timeout'></a>timeout</b> <font face='Lucida Console'>(</font>  
            T<font color='#5555FF'>&amp;</font> object,
            <font color='#0000FF'><u>void</u></font> <font face='Lucida Console'>(</font>T::<font color='#5555FF'>*</font>callback_function<font face='Lucida Console'>)</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>,
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> ms_to_timeout
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - callback_function does not throw
            ensures                
                - does not block.
                - #*this is properly initialized
                - if (this object isn't destructed in ms_to_timeout milliseconds) then
                    - (object.*callback_function)() will be called in ms_to_timeout 
                      milliseconds.
            throws
                - std::bad_alloc
                - dlib::thread_error
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> T,
            <font color='#0000FF'>typename</font> U
            <font color='#5555FF'>&gt;</font>
        <b><a name='timeout'></a>timeout</b> <font face='Lucida Console'>(</font>  
            T<font color='#5555FF'>&amp;</font> object,
            <font color='#0000FF'><u>void</u></font> <font face='Lucida Console'>(</font>T::<font color='#5555FF'>*</font>callback_function<font face='Lucida Console'>)</font><font face='Lucida Console'>(</font>U callback_function_argument<font face='Lucida Console'>)</font>,
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> ms_to_timeout,
            U callback_function_argument
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - callback_function does not throw
            ensures                
                - does not block.
                - #*this is properly initialized
                - if (this object isn't destructed in ms_to_timeout milliseconds) then
                    - (object.*callback_function)(callback_function_argument) will be 
                      called in ms_to_timeout milliseconds.
            throws
                - std::bad_alloc
                - dlib::thread_error
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> T
            <font color='#5555FF'>&gt;</font>
        <b><a name='timeout'></a>timeout</b> <font face='Lucida Console'>(</font>  
            T<font color='#5555FF'>&amp;</font> object,
            <font color='#0000FF'><u>int</u></font> <font face='Lucida Console'>(</font>T::<font color='#5555FF'>*</font>callback_function<font face='Lucida Console'>)</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>,
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> ms_to_timeout
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - callback_function does not throw
            ensures                
                - does not block.
                - #*this is properly initialized
                - if (this object isn't destructed in ms_to_timeout milliseconds) then
                    - (object.*callback_function)() will be called in ms_to_timeout 
                      milliseconds.
            throws
                - std::bad_alloc
                - dlib::thread_error
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> T,
            <font color='#0000FF'>typename</font> U
            <font color='#5555FF'>&gt;</font>
        <b><a name='timeout'></a>timeout</b> <font face='Lucida Console'>(</font>  
            T<font color='#5555FF'>&amp;</font> object,
            <font color='#0000FF'><u>int</u></font> <font face='Lucida Console'>(</font>T::<font color='#5555FF'>*</font>callback_function<font face='Lucida Console'>)</font><font face='Lucida Console'>(</font>U callback_function_argument<font face='Lucida Console'>)</font>,
            <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> ms_to_timeout,
            U callback_function_argument
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - callback_function does not throw
            ensures                
                - does not block.
                - #*this is properly initialized
                - if (this object isn't destructed in ms_to_timeout milliseconds) then
                    - (object.*callback_function)(callback_function_argument) will be 
                      called in ms_to_timeout milliseconds.
            throws
                - std::bad_alloc
                - dlib::thread_error
        !*/</font>

        <font color='#0000FF'>virtual</font> ~<b><a name='timeout'></a>timeout</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - is not called from inside the callback_function given to the
                  constructor.
            ensures
                - any resources associated with *this have been released
                - if (the callback_function hasn't been called yet) then
                    - the callback_function specified in the constructor will not be called
        !*/</font>

    <font color='#0000FF'>private</font>:

        <font color='#009900'>// restricted functions
</font>        <b><a name='timeout'></a>timeout</b><font face='Lucida Console'>(</font><font color='#0000FF'>const</font> timeout<font color='#5555FF'>&amp;</font><font face='Lucida Console'>)</font>;        <font color='#009900'>// copy constructor
</font>        timeout<font color='#5555FF'>&amp;</font> <b><a name='operator'></a>operator</b><font color='#5555FF'>=</font><font face='Lucida Console'>(</font><font color='#0000FF'>const</font> timeout<font color='#5555FF'>&amp;</font><font face='Lucida Console'>)</font>;    <font color='#009900'>// assignment operator
</font>
    <b>}</b>;    

<b>}</b>

<font color='#0000FF'>#endif</font> <font color='#009900'>// DLIB_TIMEOUT_KERNEl_ABSTRACT_
</font>


</pre></body></html>