AuroraMiddleware/asio
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Added documentation for some of the "concepts" used in asio.

Browse Source
This commit is contained in:
chris 2004-05-24 09:03:29 +00:00
parent a20ebc7fa6
commit 88901c7413
27 changed files with 591 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
asio/include/asio/basic_demuxer.hpp
View File

@ -45,6 +45,9 @@ namespace asio {
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Safe, with the exception that calling reset()
* while there are unfinished run() calls results in undefined behaviour.
*
* @par Concepts:
* Dispatcher.
*/
template <typename Demuxer_Service>
class basic_demuxer

3
asio/include/asio/basic_dgram_socket.hpp
View File

@ -36,6 +36,9 @@ namespace asio {
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object.
*/
template <typename Service>
class basic_dgram_socket

16
asio/include/asio/basic_locking_dispatcher.hpp
View File

@ -36,6 +36,9 @@ namespace asio {
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Safe.
*
* @par Concepts:
* Async_Object, Dispatcher.
*/
template <typename Service>
class basic_locking_dispatcher
@ -71,6 +74,19 @@ public:
service_.destroy(impl_);
}
/// Get the demuxer associated with the asynchronous object.
/**
* This function may be used to obtain the demuxer object that the locking
* dispatcher uses to dispatch handlers for asynchronous operations.
*
* @return A reference to the demuxer object that the dispatcher will use to
* dispatch handlers. Ownership is not transferred to the caller.
*/
demuxer_type& demuxer()
{
return service_.demuxer();
}
/// Request the dispatcher to invoke the given handler.
/**
* This function is used to ask the dispatcher to execute the given handler.

3
asio/include/asio/basic_socket_acceptor.hpp
View File

@ -36,6 +36,9 @@ namespace asio {
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object.
*/
template <typename Service>
class basic_socket_acceptor

3
asio/include/asio/basic_socket_connector.hpp
View File

@ -36,6 +36,9 @@ namespace asio {
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object.
*/
template <typename Service>
class basic_socket_connector

6
asio/include/asio/basic_stream_socket.hpp
View File

@ -36,6 +36,10 @@ namespace asio {
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object, Async_Recv_Stream, Async_Send_Stream, Stream,
* Sync_Recv_Stream, Sync_Send_Stream.
*/
template <typename Service>
class basic_stream_socket
@ -422,7 +426,7 @@ public:
* @param max_length The maximum size of the data to be received, in bytes.
*
* @param handler The handler to be called when the receive operation
* completes. Copies will be made of the handler as required. The equivalent\
* completes. Copies will be made of the handler as required. The equivalent
* function signature of the handler must be:
* @code void handler(
* const asio::socket_error& error, // Result of operation

3
asio/include/asio/basic_timer.hpp
View File

@ -36,6 +36,9 @@ namespace asio {
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object.
*/
template <typename Service>
class basic_timer

29
asio/include/asio/buffered_recv_stream.hpp
View File

@ -29,9 +29,20 @@
namespace asio {
/// The buffered_recv_stream class template can be used to add buffering to the
/// recv-related operations of a stream.
template <typename Next_Layer, typename Buffer>
/// Adds buffering to the receive-related operations of a stream.
/**
* The buffered_recv_stream class template can be used to add buffering to the
* synchronous and asynchronous receive operations of a stream.
*
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object, Async_Recv_Stream, Async_Send_Stream, Stream,
* Sync_Recv_Stream, Sync_Send_Stream.
*/
template <typename Stream, typename Buffer>
class buffered_recv_stream
: private boost::noncopyable
{
@ -45,7 +56,7 @@ public:
}
/// The type of the next layer.
typedef typename boost::remove_reference<Next_Layer>::type next_layer_type;
typedef typename boost::remove_reference<Stream>::type next_layer_type;
/// Get a reference to the next layer.
next_layer_type& next_layer()
@ -143,7 +154,7 @@ public:
class fill_handler
{
public:
fill_handler(buffered_recv_stream<Next_Layer, Buffer>& stream,
fill_handler(buffered_recv_stream<Stream, Buffer>& stream,
size_t previous_size, Handler handler)
: stream_(stream),
previous_size_(previous_size),
@ -160,7 +171,7 @@ public:
}
private:
buffered_recv_stream<Next_Layer, Buffer>& stream_;
buffered_recv_stream<Stream, Buffer>& stream_;
size_t previous_size_;
Handler handler_;
};
@ -199,7 +210,7 @@ public:
class recv_handler
{
public:
recv_handler(buffered_recv_stream<Next_Layer, Buffer>& stream, void* data,
recv_handler(buffered_recv_stream<Stream, Buffer>& stream, void* data,
size_t max_length, Handler handler)
: stream_(stream),
data_(data),
@ -229,7 +240,7 @@ public:
}
private:
buffered_recv_stream<Next_Layer, Buffer>& stream_;
buffered_recv_stream<Stream, Buffer>& stream_;
void* data_;
size_t max_length_;
Handler handler_;
@ -267,7 +278,7 @@ private:
}
/// The next layer.
Next_Layer next_layer_;
Stream next_layer_;
// The data in the buffer.
Buffer buffer_;

2
asio/include/asio/buffered_recv_stream_fwd.hpp
View File

@ -21,7 +21,7 @@
namespace asio {
template <typename Next_Layer, typename Buffer = fixed_buffer<8192> >
template <typename Stream, typename Buffer = fixed_buffer<8192> >
class buffered_recv_stream;
} // namespace asio

29
asio/include/asio/buffered_send_stream.hpp
View File

@ -28,9 +28,20 @@
namespace asio {
/// The buffered_send_stream class template can be used to add buffering to the
/// send-related operations of a stream.
template <typename Next_Layer, typename Buffer>
/// Adds buffering to the send-related operations of a stream.
/**
* The buffered_send_stream class template can be used to add buffering to the
* synchronous and asynchronous send operations of a stream.
*
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object, Async_Recv_Stream, Async_Send_Stream, Stream,
* Sync_Recv_Stream, Sync_Send_Stream.
*/
template <typename Stream, typename Buffer>
class buffered_send_stream
: private boost::noncopyable
{
@ -44,7 +55,7 @@ public:
}
/// The type of the next layer.
typedef typename boost::remove_reference<Next_Layer>::type next_layer_type;
typedef typename boost::remove_reference<Stream>::type next_layer_type;
/// Get a reference to the next layer.
next_layer_type& next_layer()
@ -114,7 +125,7 @@ public:
class flush_handler
{
public:
flush_handler(buffered_send_stream<Next_Layer, Buffer>& stream,
flush_handler(buffered_send_stream<Stream, Buffer>& stream,
Handler handler)
: stream_(stream),
handler_(handler)
@ -131,7 +142,7 @@ public:
}
private:
buffered_send_stream<Next_Layer, Buffer>& stream_;
buffered_send_stream<Stream, Buffer>& stream_;
Handler handler_;
};
@ -166,7 +177,7 @@ public:
class send_handler
{
public:
send_handler(buffered_send_stream<Next_Layer, Buffer>& stream,
send_handler(buffered_send_stream<Stream, Buffer>& stream,
const void* data, size_t length, Handler handler)
: stream_(stream),
data_(data),
@ -197,7 +208,7 @@ public:
}
private:
buffered_send_stream<Next_Layer, Buffer>& stream_;
buffered_send_stream<Stream, Buffer>& stream_;
const void* data_;
size_t length_;
Handler handler_;
@ -260,7 +271,7 @@ private:
}
/// The next layer.
Next_Layer next_layer_;
Stream next_layer_;
// The data in the buffer.
Buffer buffer_;

2
asio/include/asio/buffered_send_stream_fwd.hpp
View File

@ -21,7 +21,7 @@
namespace asio {
template <typename Next_Layer, typename Buffer = fixed_buffer<8192> >
template <typename Stream, typename Buffer = fixed_buffer<8192> >
class buffered_send_stream;
} // namespace asio

21
asio/include/asio/buffered_stream.hpp
View File

@ -27,9 +27,20 @@
namespace asio {
/// The buffered_stream class template can be used to add buffering to both the
/// send- and recv- related operations of a stream.
template <typename Next_Layer, typename Buffer>
/// Adds buffering to the send- and receive-related operations of a stream.
/**
* The buffered_stream class template can be used to add buffering to the
* synchronous and asynchronous send and receive operations of a stream.
*
* @par Thread Safety:
* @e Distinct @e objects: Safe.@n
* @e Shared @e objects: Unsafe.
*
* @par Concepts:
* Async_Object, Async_Recv_Stream, Async_Send_Stream, Stream,
* Sync_Recv_Stream, Sync_Send_Stream.
*/
template <typename Stream, typename Buffer>
class buffered_stream
: private boost::noncopyable
{
@ -42,7 +53,7 @@ public:
}
/// The type of the next layer.
typedef typename boost::remove_reference<Next_Layer>::type next_layer_type;
typedef typename boost::remove_reference<Stream>::type next_layer_type;
/// Get a reference to the next layer.
next_layer_type& next_layer()
@ -185,7 +196,7 @@ public:
private:
/// The buffered stream implementation.
buffered_recv_stream<buffered_send_stream<Next_Layer, Buffer>, Buffer>
buffered_recv_stream<buffered_send_stream<Stream, Buffer>, Buffer>
stream_impl_;
};

2
asio/include/asio/buffered_stream_fwd.hpp
View File

@ -21,7 +21,7 @@
namespace asio {
template <typename Next_Layer, typename Buffer = fixed_buffer<8192> >
template <typename Stream, typename Buffer = fixed_buffer<8192> >
class buffered_stream;
} // namespace asio

8
asio/include/asio/is_recv_buffered.hpp
View File

@ -24,11 +24,11 @@ namespace asio {
namespace detail {
template <typename Next_Layer, typename Buffer>
char is_recv_buffered_helper(buffered_stream<Next_Layer, Buffer>* s);
template <typename Stream, typename Buffer>
char is_recv_buffered_helper(buffered_stream<Stream, Buffer>* s);
template <typename Next_Layer, typename Buffer>
char is_recv_buffered_helper(buffered_recv_stream<Next_Layer, Buffer>* s);
template <typename Stream, typename Buffer>
char is_recv_buffered_helper(buffered_recv_stream<Stream, Buffer>* s);
struct is_recv_buffered_big_type { char data[10]; };
is_recv_buffered_big_type is_recv_buffered_helper(...);

8
asio/include/asio/is_send_buffered.hpp
View File

@ -24,11 +24,11 @@ namespace asio {
namespace detail {
template <typename Next_Layer, typename Buffer>
char is_send_buffered_helper(buffered_stream<Next_Layer, Buffer>* s);
template <typename Stream, typename Buffer>
char is_send_buffered_helper(buffered_stream<Stream, Buffer>* s);
template <typename Next_Layer, typename Buffer>
char is_send_buffered_helper(buffered_send_stream<Next_Layer, Buffer>* s);
template <typename Stream, typename Buffer>
char is_send_buffered_helper(buffered_send_stream<Stream, Buffer>* s);
struct is_send_buffered_big_type { char data[10]; };
is_send_buffered_big_type is_send_buffered_helper(...);

88
asio/include/asio/recv.hpp
View File

@ -27,7 +27,8 @@ namespace asio {
* This function is used to receive data on a stream. The function call will
* block until data has received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Sync_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
*
@ -44,8 +45,8 @@ namespace asio {
* the requested amount of data is received before the blocking operation
* completes.
*/
template <typename Stream>
inline size_t recv(Stream& s, void* data, size_t max_length)
template <typename Sync_Recv_Stream>
inline size_t recv(Sync_Recv_Stream& s, void* data, size_t max_length)
{
return s.recv(data, max_length);
}
@ -55,7 +56,8 @@ inline size_t recv(Stream& s, void* data, size_t max_length)
* This function is used to receive data on a stream. The function call will
* block until data has received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Sync_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
*
@ -78,8 +80,8 @@ inline size_t recv(Stream& s, void* data, size_t max_length)
* the requested amount of data is received before the blocking operation
* completes.
*/
template <typename Stream, typename Error_Handler>
inline size_t recv(Stream& s, void* data, size_t max_length,
template <typename Sync_Recv_Stream, typename Error_Handler>
inline size_t recv(Sync_Recv_Stream& s, void* data, size_t max_length,
Error_Handler error_handler)
{
return s.recv(data, max_length, error_handler);
@ -90,7 +92,8 @@ inline size_t recv(Stream& s, void* data, size_t max_length,
* This function is used to asynchronously receive data on a stream. The
* function call always returns immediately.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Async_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
* Ownership of the buffer is retained by the caller, which must guarantee
@ -113,8 +116,8 @@ inline size_t recv(Stream& s, void* data, size_t max_length,
* ensure that the requested amount of data is received before the asynchronous
* operation completes.
*/
template <typename Stream, typename Handler>
inline void async_recv(Stream& s, void* data, size_t max_length,
template <typename Async_Recv_Stream, typename Handler>
inline void async_recv(Async_Recv_Stream& s, void* data, size_t max_length,
Handler handler)
{
s.async_recv(data, max_length, handler);
@ -126,7 +129,8 @@ inline void async_recv(Stream& s, void* data, size_t max_length,
* stream. The function call will block until the specified number of bytes has
* been received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Sync_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
*
@ -141,8 +145,8 @@ inline void async_recv(Stream& s, void* data, size_t max_length,
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's recv operation.
*/
template <typename Stream>
size_t recv_n(Stream& s, void* data, size_t length,
template <typename Sync_Recv_Stream>
size_t recv_n(Sync_Recv_Stream& s, void* data, size_t length,
size_t* total_bytes_recvd = 0)
{
int bytes_recvd = 0;
@ -170,7 +174,8 @@ size_t recv_n(Stream& s, void* data, size_t length,
* stream. The function call will block until the specified number of bytes has
* been received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Sync_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
*
@ -191,8 +196,8 @@ size_t recv_n(Stream& s, void* data, size_t length,
* @returns The number of bytes received on the last recv, or 0 if end-of-file
* was reached or the connection was closed cleanly.
*/
template <typename Stream, typename Error_Handler>
size_t recv_n(Stream& s, void* data, size_t length,
template <typename Sync_Recv_Stream, typename Error_Handler>
size_t recv_n(Sync_Recv_Stream& s, void* data, size_t length,
size_t* total_bytes_recvd, Error_Handler error_handler)
{
int bytes_recvd = 0;
@ -216,11 +221,12 @@ size_t recv_n(Stream& s, void* data, size_t length,
namespace detail
{
template <typename Stream, typename Handler>
template <typename Async_Recv_Stream, typename Handler>
class recv_n_handler
{
public:
recv_n_handler(Stream& stream, void* data, size_t length, Handler handler)
recv_n_handler(Async_Recv_Stream& stream, void* data, size_t length,
Handler handler)
: stream_(stream),
data_(data),
length_(length),
@ -246,7 +252,7 @@ namespace detail
}
private:
Stream& stream_;
Async_Recv_Stream& stream_;
void* data_;
size_t length_;
size_t total_recvd_;
@ -260,7 +266,8 @@ namespace detail
* This function is used to asynchronously receive an exact number of bytes of
* data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Async_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
* Ownership of the buffer is retained by the caller, which must guarantee
@ -281,11 +288,13 @@ namespace detail
* size_t total_bytes_recvd // Total number of bytes successfully received
* ); @endcode
*/
template <typename Stream, typename Handler>
inline void async_recv_n(Stream& s, void* data, size_t length, Handler handler)
template <typename Async_Recv_Stream, typename Handler>
inline void async_recv_n(Async_Recv_Stream& s, void* data, size_t length,
Handler handler)
{
async_recv(s, data, length,
detail::recv_n_handler<Stream, Handler>(s, data, length, handler));
detail::recv_n_handler<Async_Recv_Stream, Handler>(s, data, length,
handler));
}
/// Read at least the specified amount of data from the stream before
@ -295,7 +304,8 @@ inline void async_recv_n(Stream& s, void* data, size_t length, Handler handler)
* data on a stream. The function call will block until at least that number of
* bytes has been received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Sync_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
*
@ -312,8 +322,8 @@ inline void async_recv_n(Stream& s, void* data, size_t length, Handler handler)
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's recv operation.
*/
template <typename Stream>
size_t recv_at_least_n(Stream& s, void* data, size_t min_length,
template <typename Sync_Recv_Stream>
size_t recv_at_least_n(Sync_Recv_Stream& s, void* data, size_t min_length,
size_t max_length, size_t* total_bytes_recvd = 0)
{
int bytes_recvd = 0;
@ -344,7 +354,8 @@ size_t recv_at_least_n(Stream& s, void* data, size_t min_length,
* data on a stream. The function call will block until at least that number of
* bytes has been received successfully or an error occurs.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Sync_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
*
@ -367,8 +378,8 @@ size_t recv_at_least_n(Stream& s, void* data, size_t min_length,
* @returns The number of bytes received on the last recv, or 0 if end-of-file
* was reached or the connection was closed cleanly.
*/
template <typename Stream, typename Error_Handler>
size_t recv_at_least_n(Stream& s, void* data, size_t min_length,
template <typename Sync_Recv_Stream, typename Error_Handler>
size_t recv_at_least_n(Sync_Recv_Stream& s, void* data, size_t min_length,
size_t max_length, size_t* total_bytes_recvd, Error_Handler error_handler)
{
int bytes_recvd = 0;
@ -394,12 +405,12 @@ size_t recv_at_least_n(Stream& s, void* data, size_t min_length,
namespace detail
{
template <typename Stream, typename Handler>
template <typename Async_Recv_Stream, typename Handler>
class recv_at_least_n_handler
{
public:
recv_at_least_n_handler(Stream& stream, void* data, size_t min_length,
size_t max_length, Handler handler)
recv_at_least_n_handler(Async_Recv_Stream& stream, void* data,
size_t min_length, size_t max_length, Handler handler)
: stream_(stream),
data_(data),
min_length_(min_length),
@ -426,7 +437,7 @@ namespace detail
}
private:
Stream& stream_;
Async_Recv_Stream& stream_;
void* data_;
size_t min_length_;
size_t max_length_;
@ -441,7 +452,8 @@ namespace detail
* This function is used to asynchronously receive at least a specified number
* of bytes of data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be received.
* @param s The stream on which the data is to be received. The type must
* support the Async_Recv_Stream concept.
*
* @param data The buffer into which the received data will be written.
* Ownership of the buffer is retained by the caller, which must guarantee
@ -464,15 +476,15 @@ namespace detail
* size_t total_bytes_recvd // Total number of bytes successfully received
* ); @endcode
*/
template <typename Stream, typename Handler>
inline void async_recv_at_least_n(Stream& s, void* data, size_t min_length,
size_t max_length, Handler handler)
template <typename Async_Recv_Stream, typename Handler>
inline void async_recv_at_least_n(Async_Recv_Stream& s, void* data,
size_t min_length, size_t max_length, Handler handler)
{
if (max_length < min_length)
min_length = max_length;
async_recv(s, data, max_length,
detail::recv_at_least_n_handler<Stream, Handler>(s, data, min_length,
max_length, handler));
detail::recv_at_least_n_handler<Async_Recv_Stream, Handler>(s, data,
min_length, max_length, handler));
}
} // namespace asio

87
asio/include/asio/send.hpp
View File

@ -26,7 +26,8 @@ namespace asio {
* This function is used to send data on a stream. The function call will block
* until the data has been sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Sync_Send_Stream concept.
*
* @param data The data to be sent on the stream.
*
@ -42,8 +43,8 @@ namespace asio {
* Consider using the asio::send_n() function if you need to ensure that all
* data is sent before the blocking operation completes.
*/
template <typename Stream>
inline size_t send(Stream& s, const void* data, size_t length)
template <typename Sync_Send_Stream>
inline size_t send(Sync_Send_Stream& s, const void* data, size_t length)
{
return s.send(data, length);
}
@ -53,7 +54,8 @@ inline size_t send(Stream& s, const void* data, size_t length)
* This function is used to send data on a stream. The function call will block
* until the data has been sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Sync_Send_Stream concept.
*
* @param data The data to be sent on the stream.
*
@ -75,8 +77,8 @@ inline size_t send(Stream& s, const void* data, size_t length)
* Consider using the asio::send_n() function if you need to ensure that all
* data is sent before the blocking operation completes.
*/
template <typename Stream, typename Error_Handler>
inline size_t send(Stream& s, const void* data, size_t length,
template <typename Sync_Send_Stream, typename Error_Handler>
inline size_t send(Sync_Send_Stream& s, const void* data, size_t length,
Error_Handler error_handler)
{
return s.send(data, length, error_handler);
@ -87,7 +89,8 @@ inline size_t send(Stream& s, const void* data, size_t length,
* This function is used to asynchronously send data on a stream. The function
* call always returns immediately.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Async_Send_Stream concept.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
@ -109,8 +112,8 @@ inline size_t send(Stream& s, const void* data, size_t length,
* Consider using the asio::async_send_n() function if you need to ensure that
* all data is sent before the asynchronous operation completes.
*/
template <typename Stream, typename Handler>
inline void async_send(Stream& s, const void* data, size_t length,
template <typename Async_Send_Stream, typename Handler>
inline void async_send(Async_Send_Stream& s, const void* data, size_t length,
Handler handler)
{
s.async_send(data, length, handler);
@ -122,7 +125,8 @@ inline void async_send(Stream& s, const void* data, size_t length,
* The function call will block until the specified number of bytes has been
* sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Sync_Send_Stream concept.
*
* @param data The data to be sent on the stream.
*
@ -137,8 +141,8 @@ inline void async_send(Stream& s, const void* data, size_t length,
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's send operation.
*/
template <typename Stream>
size_t send_n(Stream& s, const void* data, size_t length,
template <typename Sync_Send_Stream>
size_t send_n(Sync_Send_Stream& s, const void* data, size_t length,
size_t* total_bytes_sent = 0)
{
int bytes_sent = 0;
@ -166,7 +170,8 @@ size_t send_n(Stream& s, const void* data, size_t length,
* The function call will block until the specified number of bytes has been
* sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Sync_Send_Stream concept.
*
* @param data The data to be sent on the stream.
*
@ -187,8 +192,8 @@ size_t send_n(Stream& s, const void* data, size_t length,
* @returns The number of bytes sent on the last send, or 0 if end-of-file was
* reached or the connection was closed cleanly.
*/
template <typename Stream, typename Error_Handler>
size_t send_n(Stream& s, const void* data, size_t length,
template <typename Sync_Send_Stream, typename Error_Handler>
size_t send_n(Sync_Send_Stream& s, const void* data, size_t length,
size_t* total_bytes_sent, Error_Handler error_handler)
{
int bytes_sent = 0;
@ -212,11 +217,11 @@ size_t send_n(Stream& s, const void* data, size_t length,
namespace detail
{
template <typename Stream, typename Handler>
template <typename Async_Send_Stream, typename Handler>
class send_n_handler
{
public:
send_n_handler(Stream& stream, const void* data, size_t length,
send_n_handler(Async_Send_Stream& stream, const void* data, size_t length,
Handler handler)
: stream_(stream),
data_(data),
@ -244,7 +249,7 @@ namespace detail
}
private:
Stream& stream_;
Async_Send_Stream& stream_;
const void* data_;
size_t length_;
size_t total_sent_;
@ -258,7 +263,8 @@ namespace detail
* This function is used to asynchronously send an exact number of bytes of
* data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Async_Send_Stream concept.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
@ -278,12 +284,13 @@ namespace detail
* size_t total_bytes_sent // Total number of bytes successfully sent
* ); @endcode
*/
template <typename Stream, typename Handler>
inline void async_send_n(Stream& s, const void* data, size_t length,
template <typename Async_Send_Stream, typename Handler>
inline void async_send_n(Async_Send_Stream& s, const void* data, size_t length,
Handler handler)
{
async_send(s, data, length,
detail::send_n_handler<Stream, Handler>(s, data, length, handler));
detail::send_n_handler<Async_Send_Stream, Handler>(s, data, length,
handler));
}
/// Write at least a specified number of bytes of data to the stream before
@ -293,7 +300,8 @@ inline void async_send_n(Stream& s, const void* data, size_t length,
* on a stream. The function call will block until at least that number of
* bytes has been sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Sync_Send_Stream concept.
*
* @param data The data to be sent on the stream.
*
@ -310,9 +318,9 @@ inline void async_send_n(Stream& s, const void* data, size_t length,
* @note Throws an exception on failure. The type of the exception depends
* on the underlying stream's send operation.
*/
template <typename Stream>
size_t send_at_least_n(Stream& s, const void* data, size_t min_length,
size_t max_length, size_t* total_bytes_sent = 0)
template <typename Sync_Send_Stream>
size_t send_at_least_n(Sync_Send_Stream& s, const void* data,
size_t min_length, size_t max_length, size_t* total_bytes_sent = 0)
{
int bytes_sent = 0;
size_t total_sent = 0;
@ -342,7 +350,8 @@ size_t send_at_least_n(Stream& s, const void* data, size_t min_length,
* on a stream. The function call will block until at least that number of
* bytes has been sent successfully or an error occurs.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Sync_Send_Stream concept.
*
* @param data The data to be sent on the stream.
*
@ -365,9 +374,10 @@ size_t send_at_least_n(Stream& s, const void* data, size_t min_length,
* @returns The number of bytes sent on the last send, or 0 if end-of-file was
* reached or the connection was closed cleanly.
*/
template <typename Stream, typename Error_Handler>
size_t send_at_least_n(Stream& s, const void* data, size_t min_length,
size_t max_length, size_t* total_bytes_sent, Error_Handler error_handler)
template <typename Sync_Send_Stream, typename Error_Handler>
size_t send_at_least_n(Sync_Send_Stream& s, const void* data,
size_t min_length, size_t max_length, size_t* total_bytes_sent,
Error_Handler error_handler)
{
int bytes_sent = 0;
size_t total_sent = 0;
@ -392,11 +402,11 @@ size_t send_at_least_n(Stream& s, const void* data, size_t min_length,
namespace detail
{
template <typename Stream, typename Handler>
template <typename Async_Send_Stream, typename Handler>
class send_at_least_n_handler
{
public:
send_at_least_n_handler(Stream& stream, const void* data,
send_at_least_n_handler(Async_Send_Stream& stream, const void* data,
size_t min_length, size_t max_length, Handler handler)
: stream_(stream),
data_(data),
@ -425,7 +435,7 @@ namespace detail
}
private:
Stream& stream_;
Async_Send_Stream& stream_;
const void* data_;
size_t min_length_;
size_t max_length_;
@ -440,7 +450,8 @@ namespace detail
* This function is used to asynchronously send at least a specified number of
* bytes of data on a stream. The function call always returns immediately.
*
* @param s The stream on which the data is to be sent.
* @param s The stream on which the data is to be sent. The type must support
* the Async_Send_Stream concept.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
@ -462,15 +473,15 @@ namespace detail
* size_t total_bytes_sent // Total number of bytes successfully sent
* ); @endcode
*/
template <typename Stream, typename Handler>
inline void async_send_at_least_n(Stream& s, const void* data,
template <typename Async_Send_Stream, typename Handler>
inline void async_send_at_least_n(Async_Send_Stream& s, const void* data,
size_t min_length, size_t max_length, Handler handler)
{
if (max_length < min_length)
min_length = max_length;
async_send(s, data, max_length,
detail::send_at_least_n_handler<Stream, Handler>(s, data, min_length,
max_length, handler));
detail::send_at_least_n_handler<Async_Send_Stream, Handler>(s, data,
min_length, max_length, handler));
}
} // namespace asio

7
asio/src/doc/Makefile.am
View File

@ -23,6 +23,13 @@ EXTRA_DIST = \
asio.css \
asio_dox.txt \
release_checklist.htm \
concepts/Async_Object.hpp \
concepts/Async_Recv_Stream.hpp \
concepts/Async_Send_Stream.hpp \
concepts/Dispatcher.hpp \
concepts/Stream.hpp \
concepts/Sync_Recv_Stream.hpp \
concepts/Sync_Send_Stream.hpp \
../examples/tutorial/daytime_dox.txt \
../examples/tutorial/index_dox.txt \
../examples/tutorial/timer_dox.txt

2
asio/src/doc/asio.dox.in
View File

@ -357,7 +357,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = @srcdir@/../../include @srcdir@/../../include/asio @srcdir@/../../include/asio/ipv4 @srcdir@/asio_dox.txt @srcdir@/../examples/tutorial/index_dox.txt @srcdir@/../examples/tutorial/timer_dox.txt @srcdir@/../examples/tutorial/daytime_dox.txt
INPUT = @srcdir@/../../include @srcdir@/../../include/asio @srcdir@/../../include/asio/ipv4 @srcdir@/concepts @srcdir@/asio_dox.txt @srcdir@/../examples/tutorial/index_dox.txt @srcdir@/../examples/tutorial/timer_dox.txt @srcdir@/../examples/tutorial/daytime_dox.txt
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp

23
asio/src/doc/asio_dox.txt
View File

@ -56,6 +56,20 @@ documentation</a> for more information on how to use <tt>boost::bind</tt>.
\li asio::thread
\li asio::timer_base
<H2>Free Functions</H2>
\li asio::recv
\li asio::recv_n
\li asio::recv_at_least_n
\li asio::send
\li asio::send_n
\li asio::send_at_least_n
\li asio::async_recv
\li asio::async_recv_n
\li asio::async_recv_at_least_n
\li asio::async_send
\li asio::async_send_n
\li asio::async_send_at_least_n
</TD>
<TD VALIGN="TOP">
@ -81,6 +95,15 @@ documentation</a> for more information on how to use <tt>boost::bind</tt>.
\li asio::is_recv_buffered
\li asio::is_send_buffered
<H2>Concepts</H2>
\li Async_Object
\li Async_Recv_Stream
\li Async_Send_Stream
\li Dispatcher
\li Sync_Recv_Stream
\li Sync_Send_Stream
</TD>
</TR>
</TABLE>

43
asio/src/doc/concepts/Async_Object.hpp Normal file
View File

@ -0,0 +1,43 @@
//
// Async_Object.hpp
// ~~~~~~~~~~~~~~~~
//
// Copyright (c) 2003, 2004 Christopher M. Kohlhoff (chris@kohlhoff.com)
//
// Permission to use, copy, modify, distribute and sell this software and its
// documentation for any purpose is hereby granted without fee, provided that
// the above copyright notice appears in all copies and that both the copyright
// notice and this permission notice appear in supporting documentation. This
// software is provided "as is" without express or implied warranty, and with
// no claim as to its suitability for any purpose.
//
/// Asynchronous object concept.
/**
* @par Implemented By:
* asio::basic_dgram_socket @n
* asio::basic_locking_dispatcher @n
* asio::basic_socket_acceptor @n
* asio::basic_socket_connector @n
* asio::basic_stream_socket @n
* asio::basic_timer @n
* asio::buffered_recv_stream @n
* asio::buffered_send_stream @n
* asio::buffered_stream
*/
class Async_Object
{
public:
/// The demuxer type for this asynchronous object.
typedef implementation_defined demuxer_type;
/// Get the demuxer associated with the asynchronous object.
/**
* This function may be used to obtain the demuxer object that the object
* uses to dispatch handlers for asynchronous operations.
*
* @return A reference to the demuxer object that the object will use to
* dispatch handlers. Ownership is not transferred to the caller.
*/
demuxer_type& demuxer();
};

48
asio/src/doc/concepts/Async_Recv_Stream.hpp Normal file
View File

@ -0,0 +1,48 @@
//
// Async_Recv_Stream.hpp
// ~~~~~~~~~~~~~~~~~~~~~
//
// Copyright (c) 2003, 2004 Christopher M. Kohlhoff (chris@kohlhoff.com)
//
// Permission to use, copy, modify, distribute and sell this software and its
// documentation for any purpose is hereby granted without fee, provided that
// the above copyright notice appears in all copies and that both the copyright
// notice and this permission notice appear in supporting documentation. This
// software is provided "as is" without express or implied warranty, and with
// no claim as to its suitability for any purpose.
//
/// Asynchronous receive stream concept.
/**
* @par Implemented By:
* asio::basic_stream_socket @n
* asio::buffered_recv_stream @n
* asio::buffered_send_stream @n
* asio::buffered_stream
*/
class Async_Recv_Stream
: public Async_Object
{
public:
/// Start an asynchronous receive.
/**
* This function is used to asynchronously receive data from the stream. The
* function call always returns immediately.
*
* @param data The buffer into which the received data will be written.
* Ownership of the buffer is retained by the caller, which must guarantee
* that it is valid until the handler is called.
*
* @param max_length The maximum size of the data to be received, in bytes.
*
* @param handler The handler to be called when the receive operation
* completes. Copies will be made of the handler as required. The equivalent
* function signature of the handler must be:
* @code void handler(
* const implementation_defined& error, // Result of operation
* size_t bytes_recvd // Number of bytes received
* ); @endcode
*/
template <typename Handler>
void async_recv(void* data, size_t max_length, Handler handler);
};

48
asio/src/doc/concepts/Async_Send_Stream.hpp Normal file
View File

@ -0,0 +1,48 @@
//
// Async_Send_Stream.hpp
// ~~~~~~~~~~~~~~~~~~~~~
//
// Copyright (c) 2003, 2004 Christopher M. Kohlhoff (chris@kohlhoff.com)
//
// Permission to use, copy, modify, distribute and sell this software and its
// documentation for any purpose is hereby granted without fee, provided that
// the above copyright notice appears in all copies and that both the copyright
// notice and this permission notice appear in supporting documentation. This
// software is provided "as is" without express or implied warranty, and with
// no claim as to its suitability for any purpose.
//
/// Asynchronous send stream concept.
/**
* @par Implemented By:
* asio::basic_stream_socket @n
* asio::buffered_recv_stream @n
* asio::buffered_send_stream @n
* asio::buffered_stream
*/
class Async_Send_Stream
: public Async_Object
{
public:
/// Start an asynchronous send.
/**
* This function is used to asynchronously send data on the stream. The
* function call always returns immediately.
*
* @param data The data to be sent on the stream. Ownership of the data is
* retained by the caller, which must guarantee that it is valid until the
* handler is called.
*
* @param length The size of the data to be sent, in bytes.
*
* @param handler The handler to be called when the send operation completes.
* Copies will be made of the handler as required. The equivalent function
* signature of the handler must be:
* @code void handler(
* const implementation_defined& error, // Result of operation
* size_t bytes_sent // Number of bytes sent
* ); @endcode
*/
template <typename Handler>
void async_send(const void* data, size_t length, Handler handler);
};

62
asio/src/doc/concepts/Dispatcher.hpp Normal file
View File

@ -0,0 +1,62 @@
//
// Dispatcher.hpp
// ~~~~~~~~~~~~~~
//
// Copyright (c) 2003, 2004 Christopher M. Kohlhoff (chris@kohlhoff.com)
//
// Permission to use, copy, modify, distribute and sell this software and its
// documentation for any purpose is hereby granted without fee, provided that
// the above copyright notice appears in all copies and that both the copyright
// notice and this permission notice appear in supporting documentation. This
// software is provided "as is" without express or implied warranty, and with
// no claim as to its suitability for any purpose.
//
/// Dispatcher concept.
/**
* @par Implemented By:
* asio::basic_demuxer @n
* asio::basic_locking_dispatcher
*/
class Dispatcher
{
public:
/// Request the dispatcher to invoke the given handler.
/**
* This function is used to ask the dispatcher to execute the given handler.
*
* @param handler The handler to be called. The dispatcher will make
* a copy of the handler object as required. The equivalent function
* signature of the handler must be: @code void handler(); @endcode
*/
template <typename Handler>
void dispatch(Handler handler);
/// Request the dispatcher to invoke the given handler and return
/// immediately.
/**
* This function is used to ask the dispatcher to execute the given handler,
* but without allowing the dispatcher to call the handler from inside this
* function.
*
* @param handler The handler to be called. The dispatcher will make
* a copy of the handler object as required. The equivalent function
* signature of the handler must be: @code void handler(); @endcode
*/
template <typename Handler>
void post(Handler handler);
/// Create a new handler that automatically dispatches the wrapped handler
/// on the dispatcher.
/**
* This function is used to create a new handler function object that, when
* invoked, will automatically pass the wrapped handler to the dispatcher's
* dispatch() function.
*
* @param handler The handler to be wrapped. The dispatcher will make a copy
* of the handler object as required. The equivalent function signature of
* the handler must be: @code void handler(); @endcode
*/
template <typename Handler>
implementation_defined wrap(Handler handler);
};

29
asio/src/doc/concepts/Stream.hpp Normal file
View File

@ -0,0 +1,29 @@
//
// Stream.hpp
// ~~~~~~~~~~
//
// Copyright (c) 2003, 2004 Christopher M. Kohlhoff (chris@kohlhoff.com)
//
// Permission to use, copy, modify, distribute and sell this software and its
// documentation for any purpose is hereby granted without fee, provided that
// the above copyright notice appears in all copies and that both the copyright
// notice and this permission notice appear in supporting documentation. This
// software is provided "as is" without express or implied warranty, and with
// no claim as to its suitability for any purpose.
//
/// Stream concept.
/**
* @par Implemented By:
* asio::basic_stream_socket @n
* asio::buffered_recv_stream @n
* asio::buffered_send_stream @n
* asio::buffered_stream
*/
class Stream
: public Async_Recv_Stream,
public Async_Send_Stream,
public Sync_Recv_Stream,
public Sync_Send_Stream
{
};

63
asio/src/doc/concepts/Sync_Recv_Stream.hpp Normal file
View File

@ -0,0 +1,63 @@
//
// Sync_Recv_Stream.hpp
// ~~~~~~~~~~~~~~~~~~~~
//
// Copyright (c) 2003, 2004 Christopher M. Kohlhoff (chris@kohlhoff.com)
//
// Permission to use, copy, modify, distribute and sell this software and its
// documentation for any purpose is hereby granted without fee, provided that
// the above copyright notice appears in all copies and that both the copyright
// notice and this permission notice appear in supporting documentation. This
// software is provided "as is" without express or implied warranty, and with
// no claim as to its suitability for any purpose.
//
/// Synchronous receive stream concept.
/**
* @par Implemented By:
* asio::basic_stream_socket @n
* asio::buffered_recv_stream @n
* asio::buffered_send_stream @n
* asio::buffered_stream
*/
class Sync_Recv_Stream
{
public:
/// Receive some data from the stream.
/**
* This function is used to receive data from the stream. The function call
* will block until data has received successfully or an error occurs.
*
* @param data The buffer into which the received data will be written.
*
* @param max_length The maximum size of the data to be received, in bytes.
*
* @returns The number of bytes received or 0 if the connection was closed
* cleanly.
*
* @throws implementation_defined Thrown on failure.
*/
size_t recv(void* data, size_t max_length);
/// Receive some data from the stream.
/**
* This function is used to receive data from the stream. The function call
* will block until data has received successfully or an error occurs.
*
* @param data The buffer into which the received data will be written.
*
* @param max_length The maximum size of the data to be received, in bytes.
*
* @param error_handler The handler to be called when an error occurs. Copies
* will be made of the handler as required. The equivalent function signature
* of the handler must be:
* @code void error_handler(
* const asio::socket_error& error // Result of operation
* ); @endcode
*
* @returns The number of bytes received or 0 if the connection was closed
* cleanly.
*/
template <typename Error_Handler>
size_t recv(void* data, size_t max_length, Error_Handler error_handler);
};

65
asio/src/doc/concepts/Sync_Send_Stream.hpp Normal file
View File

@ -0,0 +1,65 @@
//
// Sync_Send_Stream.hpp
// ~~~~~~~~~~~~~~~~~~~~
//
// Copyright (c) 2003, 2004 Christopher M. Kohlhoff (chris@kohlhoff.com)
//
// Permission to use, copy, modify, distribute and sell this software and its
// documentation for any purpose is hereby granted without fee, provided that
// the above copyright notice appears in all copies and that both the copyright
// notice and this permission notice appear in supporting documentation. This
// software is provided "as is" without express or implied warranty, and with
// no claim as to its suitability for any purpose.
//
/// Synchronous send stream concept.
/**
* @par Implemented By:
* asio::basic_stream_socket @n
* asio::buffered_recv_stream @n
* asio::buffered_send_stream @n
* asio::buffered_stream
*/
class Sync_Send_Stream
{
public:
/// Send the given data on the stream.
/**
* This function is used to send data on the stream. The function call will
* block until some or all of the data has been sent successfully, or until
* an error occurs.
*
* @param data The data to be sent.
*
* @param length The size of the data to be sent, in bytes.
*
* @returns The number of bytes sent or 0 if the connection was closed
* cleanly.
*
* @throws implementation_specified Thrown on failure.
*/
size_t send(const void* data, size_t length);
/// Send the given data on the stream.
/**
* This function is used to send data on the stream. The function call will
* block until some or all of the data has been sent successfully, or until
* an error occurs.
*
* @param data The data to be sent.
*
* @param length The size of the data to be sent, in bytes.
*
* @param error_handler The handler to be called when an error occurs. Copies
* will be made of the handler as required. The equivalent function signature
* of the handler must be:
* @code void error_handler(
* const implementation_defined& error // Result of operation
* ); @endcode
*
* @returns The number of bytes sent or 0 if the connection was closed
* cleanly.
*/
template <typename Error_Handler>
size_t send(const void* data, size_t length, Error_Handler error_handler);
};