xtd::net::sockets::socket_async_event_args Class Reference

Inheritance diagram for xtd::net::sockets::socket_async_event_args:

Definition

Represents an asynchronous socket operation.

class core_export_ socket_async_event_args : public xtd::event_args

Inheritance

xtd::event_args → xtd::net::sockets::socket_async_event_args

Header

#include <xtd/net/sockets/socket_async_event_args>

Namespace

xtd::net::sockets

Library

xtd.core

Remarks

The xtd::net::sockets::socket_async_event_args class is part of a set of enhancements to the xtd::net::sockets::socket class that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. This class was specifically designed for network server applications that require high performance. An application can use the enhanced asynchronous pattern exclusively or only in targeted hot areas (for example, when receiving large amounts of data).

The main feature of these enhancements is the avoidance of the repeated allocation and synchronization of objects during high-volume asynchronous socket I/O. The Begin/End design pattern currently implemented by the xtd::net::sockets::socket class requires a xtd::iasync_result object be allocated for each asynchronous socket operation.

In the new xtd::net::sockets::socket class enhancements, asynchronous socket operations are described by reusable xtd::net::sockets::socket_async_event_args objects allocated and maintained by the application. High-performance socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the xtd::net::sockets::socket_async_event_args objects that it needs. For example, if a server application needs to have 15 socket accept operations outstanding at all times to support incoming client connection rates, it can allocate 15 reusable xtd::net::sockets::socket_async_event_args objects for that purpose.

The pattern for performing an asynchronous socket operation with this class consists of the following steps:

1. Allocate a new xtd::net::sockets::socket_async_event_args context object, or get a free one from an application pool.
2. Set properties on the context object to the operation about to be performed (the completion callback method, the data buffer, the offset into the buffer, and the maximum amount of data to transfer, for example).
3. Call the appropriate socket method (xxx_async) to initiate the asynchronous operation.
4. If the asynchronous socket method (xxx_async) returns true, in the callback, query the context properties for completion status.
5. If the asynchronous socket method (xxx_async) returns false, the operation completed synchronously. The context properties may be queried for the operation result.
6. Reuse the context for another operation, put it back in the pool, or discard it.

The lifetime of the new asynchronous socket operation context object is determined by references by the application code and asynchronous I/O references. It is not necessary for the application to retain a reference to an asynchronous socket operation context object after it is submitted as a parameter to one of the asynchronous socket operation methods. It will remain referenced until the completion callback returns. However it is advantageous for the application to retain the reference to the context so that it can be reused for a future asynchronous socket operation.

Public Events
xtd::event< socket_async_event_args, xtd::delegate< void(const socket_async_event_args &)> >	completed
	The event used to complete an asynchronous operation.

Public Constructors
	socket_async_event_args ()=default
	Creates an empty xtd::net::sockets::socket_async_event_args instance.
	socket_async_event_args (bool suppress_execution_context_flow)
	Initializes the SocketAsyncEventArgs.

Public Properties
xtd::net::sockets::socket	accept_socket () const noexcept
	Gets the socket to use or the socket created for accepting a connection with an asynchronous socket method.
socket_async_event_args &	accept_socket (const xtd::net::sockets::socket &value) noexcept
	Sets the socket to use or the socket created for accepting a connection with an asynchronous socket method.
const xtd::array< xtd::byte > &	buffer () const noexcept
	Gets the data buffer to use with an asynchronous socket method.
xtd::array< xtd::byte > &	buffer () noexcept
	Gets the data buffer to use with an asynchronous socket method.

Public Methods
void	set_buffer (const xtd::array< xtd::byte > &memory_buffer)
	Sets the region of memory to use as a buffer with an asynchronous socket method.
void	set_buffer (size_t offset, size_t count)
	Sets the data buffer to use with an asynchronous socket method.
void	set_buffer (const xtd::array< xtd::byte > &buffer, size_t offset, size_t count)
	Sets the data buffer to use with an asynchronous socket method.

Protected Methods
virtual void	on_complete (const socket_async_event_args &e)
	Represents a method that is called when an asynchronous operation completes.

Additional Inherited Members
static const event_args	empty
	Provides a value to use with events that do not have event data.
	event_args ()=default
	Initializes a new instance of the event_args class.
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

socket_async_event_args() [1/2]

xtd::net::sockets::socket_async_event_args::socket_async_event_args ( )

default

Creates an empty xtd::net::sockets::socket_async_event_args instance.

Remarks

After calling this constructor all properties will have their default values:

• Object references will be null.
• Properties that return an integer will return zero.
• The xtd::net::sockets::socket_async_event_args::last_operation property will be equal to xtd::net::sockets::async_operation::none.
• The xtd::net::sockets::socket_async_event_args::send_packets_flags property will be equal to xtd::net::sockets::transmit_file_options::use_default_worker_thread, which specifies no flags will be used.
• The xtd::net::sockets::socket_async_event_args::socket_flags property will be equal to xtd::net::sockets::async_operation::none.

The caller must set the appropriate properties prior to passing the object to the appropriate asynchronous socket (xxx_async) method.

socket_async_event_args() [2/2]

xtd::net::sockets::socket_async_event_args::socket_async_event_args ( bool suppress_execution_context_flow )

explicit

Initializes the SocketAsyncEventArgs.

Parameters

suppress_execution_context_flow

Whether to disable the capturing and flow of execution context. Execution context flow should only be disabled if it's handled by higher layers.

Member Function Documentation

accept_socket() [1/2]

xtd::net::sockets::socket xtd::net::sockets::socket_async_event_args::accept_socket ( ) const

noexcept

Gets the socket to use or the socket created for accepting a connection with an asynchronous socket method.

Returns

The xtd::net::sockets::socket to use or the socket created for accepting a connection with an asynchronous socket method.

Remarks

This property can be used to provide an already created Socket that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to empty) before calling the xtd::net::sockets::socket::acceptA_async method, a new socket will be created automatically and be accessible in the completion callback with this property.

accept_socket() [2/2]

socket_async_event_args & xtd::net::sockets::socket_async_event_args::accept_socket ( const xtd::net::sockets::socket & value )

noexcept

Sets the socket to use or the socket created for accepting a connection with an asynchronous socket method.

Parameters

value

The xtd::net::sockets::socket to use or the socket created for accepting a connection with an asynchronous socket method.

Returns

This current instance.

Remarks

This property can be used to provide an already created Socket that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to empty) before calling the xtd::net::sockets::socket::acceptA_async method, a new socket will be created automatically and be accessible in the completion callback with this property.

buffer() [1/2]

const xtd::array< xtd::byte > & xtd::net::sockets::socket_async_event_args::buffer ( ) const

noexcept

Gets the data buffer to use with an asynchronous socket method.

Returns

A Byte array that represents the data buffer to use with an asynchronous socket method.

Remarks

This property gets the data buffer currently associated with the xtd::net::sockets::socket_async_event_args instance. To set the buffer, the xtd::net::sockets::socket_async_event_args::set_buffer method must be used.

This property is used with the xtd::net::sockets::socket::accept_async, xtd::net::sockets::socket::connect_async, xtd::net::sockets::socket::receive_async, xtd::net::sockets::socket::receive_from_async, xtd::net::sockets::socket::receive_message_from_async, xtd::net::sockets::socket::send_async, and xtd::net::sockets::socket::send_to_async methods.

buffer() [2/2]

xtd::array< xtd::byte > & xtd::net::sockets::socket_async_event_args::buffer ( )

noexcept

Gets the data buffer to use with an asynchronous socket method.

Returns

A Byte array that represents the data buffer to use with an asynchronous socket method.

Remarks

This property gets the data buffer currently associated with the xtd::net::sockets::socket_async_event_args instance. To set the buffer, the xtd::net::sockets::socket_async_event_args::set_buffer method must be used.

This property is used with the xtd::net::sockets::socket::accept_async, xtd::net::sockets::socket::connect_async, xtd::net::sockets::socket::receive_async, xtd::net::sockets::socket::receive_from_async, xtd::net::sockets::socket::receive_message_from_async, xtd::net::sockets::socket::send_async, and xtd::net::sockets::socket::send_to_async methods.

set_buffer() [1/3]

void xtd::net::sockets::socket_async_event_args::set_buffer

(

const xtd::array< xtd::byte > &

memory_buffer

)

Sets the region of memory to use as a buffer with an asynchronous socket method.

Parameters

memory_buffer

The region of memory to use as a buffer with an asynchronous socket method.

set_buffer() [2/3]

void xtd::net::sockets::socket_async_event_args::set_buffer	(	size_t	offset,
		size_t	count )

Sets the data buffer to use with an asynchronous socket method.

Parameters

offset	The offset, in bytes, in the data buffer where the operation starts.
count	The maximum amount of data, in bytes, to send or receive in the buffer.

Exceptions

xtd::argument_out_of_range_exception

An argument was out of range. This exception occurs if the offset parameter is greater than the length of the array in the xtd::net::sockets::socket_async_event_args::buffer property. This exception also occurs if the count parameter is greater than the length of the array in the xtd::net::sockets::socket_async_event_args::buffer property minus the offset parameter.

Remarks

The offset and count parameters can't be negative numbers. The combination of the offset and count parameters must be in bounds of the buffer array in the xtd::net::sockets::socket_async_event_args::buffer property.

This method sets the xtd::net::sockets::socket_async_event_args::count property to the count parameter and the xtd::net::sockets::socket_async_event_args::offset property to the offset parameter. If the xtd::net::sockets::socket_async_event_args::buffer property is empty, this method ignores the offset and count parameters and sets the xtd::net::sockets::socket_async_event_args::offset and xtd::net::sockets::socket_async_event_args::count properties to 0.

This method does not change the xtd::net::sockets::socket_async_event_args::buffer property.

set_buffer() [3/3]

void xtd::net::sockets::socket_async_event_args::set_buffer	(	const xtd::array< xtd::byte > &	buffer,
		size_t	offset,
		size_t	count )

Sets the data buffer to use with an asynchronous socket method.

Parameters

buffer	The data buffer to use with an asynchronous socket method.
offset	The offset, in bytes, in the data buffer where the operation starts.
count	The maximum amount of data, in bytes, to send or receive in the buffer.

Exceptions

xtd::argument_out_of_range_exception

An argument was out of range. This exception occurs if the offset parameter is greater than the length of the array in the xtd::net::sockets::socket_async_event_args::buffer property. This exception also occurs if the count parameter is greater than the length of the array in the xtd::net::sockets::socket_async_event_args::buffer property minus the offset parameter.

Remarks

The offset and count parameters can't be negative numbers. The combination of the offset and count parameters must be in bounds of the data array in the buffer parameter.

This method sets the xtd::net::sockets::socket_async_event_args::buffer property to the buffer parameter, the xtd::net::sockets::socket_async_event_args::count property to the count parameter, and the xtd::net::sockets::socket_async_event_args::offset property to the offset parameter.

on_complete()

virtual void xtd::net::sockets::socket_async_event_args::on_complete ( const socket_async_event_args & e )

protectedvirtual

Represents a method that is called when an asynchronous operation completes.

Parameters

e	The event that is signaled.

Remarks

This method is not callable by user code. This method gets called by the internals of the xtd::net::sockets::socket_async_event_args object when the current operation is complete. This method is used with all asynchronous socket (xxx_async) methods.

An application that creates a class inheriting from xtd::net::sockets::socket_async_event_args can override this method to hook into this completion notification and clean up any resources that it allocated for the operation. The default implementation just raises the xtd::net::sockets::socket_async_event_args::completed event.

This method is used to hook up an event handler to be used as the completion callback for a subsequent asynchronous socket operation. The caller must implement at least one callback delegate inherited from this method prior to starting an asynchronous socket operation using one of the asynchronous (xxx_async) methods on the xtd::net::sockets::socket class.

The caller's xtd::net::sockets::socket_async_event_args::on_completed method provides a way for client applications to complete an asynchronous socket operation. A callback delegate must be implemented when an asynchronous socket operation is initiated. The completion callback delegate(s) inherited from the xtd::net::sockets::socket_async_event_args::on_completed method must contain program logic to finish processing the asynchronous socket operation for the client.

When an asynchronous operation is signaled, the application uses the xtd::net::sockets::socket_async_event_args object parameter to obtain status of the completed asynchronous socket operation.

Member Data Documentation

completed

xtd::event<socket_async_event_args, xtd::delegate<void(const socket_async_event_args&)> > xtd::net::sockets::socket_async_event_args::completed

The event used to complete an asynchronous operation.

Remarks

The xtd::net::sockets::socket_async_event_args::completed event provides a way for client applications to complete an asynchronous socket operation. An event handler should be attached to the event within a xtd::net::sockets::socket_async_event_args instance when an asynchronous socket operation is initiated, otherwise the application will not be able to determine when the operation completes.

The completion callback delegates referenced by the xtd::net::sockets::socket_async_event_args::completed event contains program logic to finish processing the asynchronous socket operation for the client.

When the event is signaled, the application uses the xtd::net::sockets::socket_async_event_args object parameter to obtain the status of the completed asynchronous socket operation.

For more information about handling events, see Handling and Raising Events.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/net/sockets/socket_async_event_args.hpp