AsyncServer< T > Class Template Reference

#include <evo/ioasync_server.h>

Inheritance diagram for AsyncServer< T >:

Detailed Description

template<class T>
class evo::AsyncServer< T >

Async I/O server for receiving and handling requests.

This is a template class that uses a ProtocolServer (T) which implements the server request handling via async I/O event methods.

• The ProtocolServer is usually also a template class that implements the protocol and uses a user-defined, protocol-specific event-handler

See Server section in: Asynchronous I/O

ProtocolServer Requirements

The ProtocolServer (T) must define this nested type:

• T::Handler: An event handler inheriting AsyncServerHandler (directly or indirectly) and implementing protocol-specific event methods

The ProtocolServer (T) must implement these event methods:

• bool on_read(size_t& fixed_size, AsyncBuffers& buffers)

  • Called when data is available to read
  • If not enough data is available, return true to wait for more
  • Return false to immediately close the connection
  • This will usually have a loop like this to read line by line:

    SubString line;
    while (buffers.read_line(line)) {
       // ...
       buffers.read_flush();
    }

  • To read fixed size data (i.e. read an additional N bytes): call buffers.read_fixed(), and if that fails (i.e. returns false):
    • This means more data is needed from the client
    • To wait for more data: set fixed_size (out param) to the desired read size and return true
    • Then on_read_fixed() will be called when enough data arrives
    • Use buffers.read_fixed_helper() to make this easier in most cases, so all fixed-size reads go through the on_read_fixed() event method
    • Caution: Do not modify fixed_size unless buffers.read_fixed() has been called and returned false

• bool on_read_fixed(size_t& next_size, SubString& data)

  • Called instead of on_read() when reading fixed-size data
    • This is only called if on_read() set a fixed_size
    • If not used this will not be called – just return false
  • Return false to immediately close connection
  • Memory referenced by data param will not be valid after this returns

• void on_error(AsyncError err)

  • Called when the client has closed the connection, or when a socket error ocurred

The ProtocolServer (T) must define this constant:

• MIN_INITIAL_READ: Minimum size (in bytes) needed before calling on_read() the first time for a request, 0 for any amount

  static const size_t MIN_INITIAL_READ = 0;

Template Parameters

T	ProtocolServer type to use (see above)

Classes
struct	Stats

Public Types
typedef ProtocolServer::Handler::DeferredContext	DeferredContext
typedef ProtocolServer::Handler::Global	Global
typedef T	ProtocolServer
typedef ProtocolServer::Handler::Shared	Shared
typedef AsyncServer< ProtocolServer >	This

Public Member Functions
	AsyncServer ()
	Constructor. More...
Global &	get_global ()
	Get reference to global data used by all requests and all threads in this server. More...
bool	run (IoSocket::Handle listener)
	Run server event handling and handle connections until shutdown. More...
bool	run (Socket &listener)
	Run server and handle connections until shutdown. More...
bool	runlocal ()
	Run the event-loop locally in current thread until all pending requests are handled (client only). More...
virtual void	set_logger (LoggerBase *newlogger)
	Set logger to use. More...
void	set_timeout (ulong read_timeout_ms=0, ulong write_timeout_ms=0)
	Set read/write timeouts to use. More...
bool	set_timer (OnTimer &on_timer, ulong msec)
	Activate timer so it expires after given time elapses. More...
void	shutdown ()
	Shut down server. More...

Public Attributes
LoggerPtr	logger
	Logger for protocol and debug messages, set to enable logging – see set_logger() More...

Protected Member Functions
virtual bool	check_client_active ()
	Called during client event-loop to check whether any client requests are active (client only). More...
void	init ()
	Initialize event-loop. More...
void	init_attach (AsyncBase &parent)
	Initialize and attach to a parent event-loop. More...
bool	run_eventloop ()
	Run event loop and process all events and repeat until shutdown. More...
bool	run_eventloop_once ()
	Run event loop with one pass and process all events. More...

Static Protected Member Functions
static struct timeval *	get_timeout_ptr (struct timeval &out, ulong ms)
	Get timeval struct pointer from timeout in milliseconds. More...

Protected Attributes
AsyncBase *	child_base_
	Pointer to child in AsyncBase chain (always an AsyncClient), NULL for none. More...
AsyncEventLoop *	evloop_
	Event loop pointer, either owned by this or a parent. More...
bool	local_
	Whether event-loop is local (same thread), false if separate thread. More...
AsyncBase *	parent_base_
	Pointer to parent in AsyncBase chain, NULL if this is the main parent (and owns evloop_ pointer) More...
ulong	read_timeout_ms_
	Socket read timeout in milliseconds, 0 for none (never timeout) More...
ulong	write_timeout_ms_
	Socket write timeout in milliseconds, 0 for none (never timeout) More...

Member Typedef Documentation

DeferredContext

typedef ProtocolServer::Handler::DeferredContext DeferredContext

Global

typedef ProtocolServer::Handler::Global Global

ProtocolServer

typedef T ProtocolServer

Shared

typedef ProtocolServer::Handler::Shared Shared

This

typedef AsyncServer<ProtocolServer> This

Constructor & Destructor Documentation

AsyncServer()

AsyncServer ( )

inline

Constructor.

Member Function Documentation

check_client_active()

virtual bool check_client_active ( )

inlineprotectedvirtualinherited

Called during client event-loop to check whether any client requests are active (client only).

• This is used to determine if all client requests were handled
• Only AsyncClient should override this, AsyncServer should leave the default

Returns

Whether any client requests are active, true if a request is in progress (waiting for response or write is pending)

get_global()

Global& get_global ( )

inline

Get reference to global data used by all requests and all threads in this server.

• Use this to populate configuration data before running the server

Returns

Reference to global data

get_timeout_ptr()

static struct timeval* get_timeout_ptr ( struct timeval &  out, ulong  ms  )

inlinestaticprotectedinherited

Get timeval struct pointer from timeout in milliseconds.

Parameters

out	Struct to store timeout
ms	Time in milliseconds to use

Returns

Pointer to out, or NULL if ms is 0

init()

void init ( )

inlineprotectedinherited

Initialize event-loop.

• Ignored if already initialized

init_attach()

void init_attach ( AsyncBase &  parent )

inlineprotectedinherited

Initialize and attach to a parent event-loop.

• Ignored if already initialized

Parameters

parent

Parent AsyncBase to attach to

run() [1/2]

bool run ( IoSocket::Handle  listener )

inline

Run server event handling and handle connections until shutdown.

• This initializes (calls Shared::on_init()) and runs the event-loop to accept and handle connections
• This keeps running until the listener socket is closed or shutdown() is called
• Caution: Only 1 thread may handle connections at a time, otherwise results are undefined

Parameters

listener

Listener socket handle to accept connections on

Returns

Whether successful, false if initialization failed (Shared::on_init() or internal error)

run() [2/2]

bool run ( Socket &  listener )

inline

Run server and handle connections until shutdown.

• This runs the event-loop to accept and handle connections
• This keeps running until the listener socket is closed or shutdown() is called
• Caution: Only 1 thread may handle connections at a time, otherwise results are undefined

Parameters

listener

Listener socket to accept connections on

Returns

Whether successful, false if initialization failed (Shared::on_init() or internal error)

run_eventloop()

bool run_eventloop ( )

inlineprotectedinherited

Run event loop and process all events and repeat until shutdown.

Returns

Whether successful, false on internal error

run_eventloop_once()

bool run_eventloop_once ( )

inlineprotectedinherited

Run event loop with one pass and process all events.

• This waits until some events are active then processes all active events and returns

Returns

Whether successful, false on internal error

runlocal()

bool runlocal ( )

inlineinherited

Run the event-loop locally in current thread until all pending requests are handled (client only).

• This blocks while client requests are pending
• This returns false immediately if this does not own an event-loop (i.e. was attached to a parent) – only the top parent can run an event-loop

Returns

Whether successful, false if attached to another AsyncBase or on internal error

set_logger()

virtual void set_logger ( LoggerBase *  newlogger )

inlinevirtualinherited

Set logger to use.

• If set, a logger shows low-level details and error information from the framework
• The logger pointer must remain valid as long as it's referenced here

Parameters

newlogger

Pointer to logger to set, NULL for none (no logging)

set_timeout()

void set_timeout ( ulong  read_timeout_ms = 0, ulong  write_timeout_ms = 0  )

inlineinherited

Set read/write timeouts to use.

Parameters

read_timeout_ms	Socket read timeout in milliseconds, 0 for none (never timeout)
write_timeout_ms	Socket write timeout in milliseconds, 0 for none (never timeout)

set_timer()

bool set_timer ( OnTimer &  on_timer, ulong  msec  )

inlineinherited

Activate timer so it expires after given time elapses.

• When the timer expires the OnTimer::on_timer() event is called and the timer is deactivated
• To reactivate the timer so it expires again the event should call OnTimer::timer_reset()

Parameters

on_timer	Timer to use
msec	Expiration time in milliseconds

Returns

Whether successful, false on internal error

shutdown()

void shutdown ( )

inline

Shut down server.

• The server will stop accepting new requests and will finish handling current requests
• This doesn't block and can be called from any thread or event handler

Member Data Documentation

child_base_

AsyncBase* child_base_

protectedinherited

Pointer to child in AsyncBase chain (always an AsyncClient), NULL for none.

evloop_

AsyncEventLoop* evloop_

protectedinherited

Event loop pointer, either owned by this or a parent.

local_

bool local_

protectedinherited

Whether event-loop is local (same thread), false if separate thread.

logger

LoggerPtr logger

inherited

Logger for protocol and debug messages, set to enable logging – see set_logger()

parent_base_

AsyncBase* parent_base_

protectedinherited

Pointer to parent in AsyncBase chain, NULL if this is the main parent (and owns evloop_ pointer)

read_timeout_ms_

ulong read_timeout_ms_

protectedinherited

Socket read timeout in milliseconds, 0 for none (never timeout)

write_timeout_ms_

ulong write_timeout_ms_

protectedinherited

Socket write timeout in milliseconds, 0 for none (never timeout)

---

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

• evo/ioasync_server.h