#include <socketengine.h>

Classes
class	Statistics

Public Types
typedef iovec	IOVector

Static Public Member Functions
static void	Init ()

static void	Deinit ()

static bool	AddFd (EventHandler *eh, int event_mask)

static void	ChangeEventMask (EventHandler *eh, int event_mask)

static size_t	GetMaxFds ()

static size_t	GetUsedFds ()

static void	DelFd (EventHandler *eh)

static bool	HasFd (int fd)

static EventHandler *	GetRef (int fd)

static int	DispatchEvents ()

static void	DispatchTrialWrites ()

static bool	BoundsCheckFd (EventHandler *eh)

static int	Accept (EventHandler fd, sockaddr addr, socklen_t *addrlen)

static int	Close (EventHandler *eh)

static int	Close (int fd)

static int	Send (EventHandler fd, const void buf, size_t len, int flags)

static int	WriteV (EventHandler fd, const IOVector iov, int count)

static int	Recv (EventHandler fd, void buf, size_t len, int flags)

static int	RecvFrom (EventHandler fd, void buf, size_t len, int flags, sockaddr from, socklen_t fromlen)

static int	SendTo (EventHandler fd, const void buf, size_t len, int flags, const irc::sockets::sockaddrs &address)

static int	Connect (EventHandler *fd, const irc::sockets::sockaddrs &address)

static int	Blocking (int fd)

static int	NonBlocking (int fd)

static int	Shutdown (EventHandler *fd, int how)

static int	Shutdown (int fd, int how)

static int	Bind (int fd, const irc::sockets::sockaddrs &addr)

static int	Listen (int sockfd, int backlog)

static void	SetReuse (int sockfd)

static void	RecoverFromFork ()

static const Statistics &	GetStats ()

static bool	IgnoreError ()

static std::string	LastError ()

static std::string	GetError (int errnum)

Detailed Description

Provides basic file-descriptor-based I/O support. The actual socketengine class presents the same interface on all operating systems, but its private members and internal behaviour should be treated as blackboxed, and vary from system to system and upon the config settings chosen by the server admin.

Member Function Documentation

◆ Accept()

int SocketEngine::Accept	(	EventHandler *	fd,
		sockaddr *	addr,
		socklen_t *	addrlen
	)

static

Abstraction for BSD sockets accept(2). This function should emulate its namesake system call exactly.

Parameters

fd	This version of the call takes an EventHandler instead of a bare file descriptor.
addr	The client IP address and port
addrlen	The size of the sockaddr parameter.

Returns: This method should return exactly the same values as the system call it emulates.

◆ AddFd()

bool SocketEngine::AddFd	(	EventHandler *	eh,
		int	event_mask
	)

static

Add an EventHandler object to the engine. Use AddFd to add a file descriptor to the engine and have the socket engine monitor it. You must provide an object derived from EventHandler which implements the required OnEventHandler*() methods.

Parameters

eh	An event handling object to add
event_mask	The initial event mask for the object

◆ Bind()

int SocketEngine::Bind	(	int	fd,
		const irc::sockets::sockaddrs &	addr
	)

static

Abstraction for BSD sockets bind(2). This function should emulate its namesake system call exactly.

Returns: This method should return exactly the same values as the system call it emulates.

◆ Blocking()

int SocketEngine::Blocking ( int fd )

static

Make a file descriptor blocking.

Parameters

fd	a file descriptor to set to blocking mode

Returns: 0 on success, -1 on failure, errno is set appropriately.

◆ BoundsCheckFd()

bool SocketEngine::BoundsCheckFd ( EventHandler * eh )

static

Returns true if the file descriptors in the given event handler are within sensible ranges which can be handled by the socket engine.

◆ ChangeEventMask()

void SocketEngine::ChangeEventMask	(	EventHandler *	eh,
		int	event_mask
	)

static

If you call this function and pass it an event handler, that event handler will receive the next available write event, even if the socket is a readable socket only. Developers should avoid constantly keeping an eventhandler in the writeable state, as this will consume large amounts of CPU time.

Parameters

eh	The event handler to change
event_mask	The changes to make to the wait state

◆ Close() [1/2]

int SocketEngine::Close ( EventHandler * eh )

static

Close the underlying fd of an event handler, remove it from the socket engine and set the fd to -1.

Parameters

eh	The EventHandler to close.

Returns: 0 on success, a negative value on error

◆ Close() [2/2]

int SocketEngine::Close ( int fd )

static

Abstraction for BSD sockets close(2). This function should emulate its namesake system call exactly. This function should emulate its namesake system call exactly.

Returns: This method should return exactly the same values as the system call it emulates.

◆ Connect()

int SocketEngine::Connect	(	EventHandler *	fd,
		const irc::sockets::sockaddrs &	address
	)

static

Abstraction for BSD sockets connect(2). This function should emulate its namesake system call exactly.

Parameters

fd	This version of the call takes an EventHandler instead of a bare file descriptor.
address	The server IP address and port.

Returns: This method should return exactly the same values as the system call it emulates.

◆ Deinit()

void SocketEngine::Deinit ( )

static

Destructor. The destructor transparently tidies up any resources used by the socket engine.

Shutdown the kqueue engine

◆ DelFd()

void SocketEngine::DelFd ( EventHandler * eh )

static

Delete an event handler from the engine. This function call deletes an EventHandler from the engine, returning true if it succeeded and false if it failed. This does not free the EventHandler pointer using delete, if this is required you must do this yourself.

Parameters

eh	The event handler object to remove

◆ DispatchEvents()

int SocketEngine::DispatchEvents ( )

static

Waits for events and dispatches them to handlers. Please note that this doesn't wait long, only a couple of milliseconds. It returns the number of events which occurred during this call. This method will dispatch events to their handlers by calling their EventHandler::OnEventHandler*() methods.

Returns: The number of events which have occurred.

◆ DispatchTrialWrites()

void SocketEngine::DispatchTrialWrites ( )

static

Dispatch trial reads and writes. This causes the actual socket I/O to happen when writes have been pre-buffered.

◆ GetError()

std::string SocketEngine::GetError ( int errnum )

static

Returns the error for the given error num, strerror(errnum) on *nix

◆ GetMaxFds()

static size_t SocketEngine::GetMaxFds ( )

inlinestatic

Returns the number of file descriptors reported by the system this program may use when it was started.

Returns: If non-zero the number of file descriptors that the system reported that we may use.

◆ GetRef()

EventHandler * SocketEngine::GetRef ( int fd )

static

Returns the EventHandler attached to a specific fd. If the fd isn't in the socketengine, returns NULL.

Parameters

fd	The event handler to look for

Returns: A pointer to the event handler, or NULL

◆ GetStats()

static const Statistics& SocketEngine::GetStats ( )

inlinestatic

Get data transfer and event statistics

◆ GetUsedFds()

static size_t SocketEngine::GetUsedFds ( )

inlinestatic

Returns the number of file descriptors being queried

Returns: The set size

◆ HasFd()

bool SocketEngine::HasFd ( int fd )

static

Returns true if a file descriptor exists in the socket engine's list.

Parameters

fd	The event handler to look for

Returns: True if this fd has an event handler

◆ IgnoreError()

bool SocketEngine::IgnoreError ( )

inlinestatic

Should we ignore the error in errno? Checks EAGAIN and WSAEWOULDBLOCK

◆ Init()

void SocketEngine::Init ( )

static

Constructor. The constructor transparently initializes the socket engine which the ircd is using. Please note that if there is a catastrophic failure (for example, you try and enable epoll on a 2.4 linux kernel) then this function may bail back to the shell.

Returns: void, but it is acceptable for this function to bail back to the shell or operating system on fatal error.

Initialize the kqueue engine

◆ LastError()

std::string SocketEngine::LastError ( )

static

Return the last socket related error. strrerror(errno) on *nix

◆ Listen()

int SocketEngine::Listen	(	int	sockfd,
		int	backlog
	)

static

Abstraction for BSD sockets listen(2). This function should emulate its namesake system call exactly.

Returns: This method should return exactly the same values as the system call it emulates.

◆ NonBlocking()

int SocketEngine::NonBlocking ( int fd )

static

Make a file descriptor nonblocking.

Parameters

fd	A file descriptor to set to nonblocking mode

Returns: 0 on success, -1 on failure, errno is set appropriately.

◆ RecoverFromFork()

void SocketEngine::RecoverFromFork ( )

static

This function is called immediately after fork(). Some socket engines (notably kqueue) cannot have their handles inherited by forked processes. This method allows for the socket engine to re-create its handle after the daemon forks as the socket engine is created long BEFORE the daemon forks.

Returns: void, but it is acceptable for this function to bail back to the shell or operating system on fatal error.

◆ Recv()

int SocketEngine::Recv	(	EventHandler *	fd,
		void *	buf,
		size_t	len,
		int	flags
	)

static

Abstraction for BSD sockets recv(2). This function should emulate its namesake system call exactly.

Parameters

fd	This version of the call takes an EventHandler instead of a bare file descriptor.
buf	The buffer in which the data that is read is stored.
len	The size of the buffer.
flags	A flag value that controls the reception of the data.

Returns: This method should return exactly the same values as the system call it emulates.

◆ RecvFrom()

int SocketEngine::RecvFrom	(	EventHandler *	fd,
		void *	buf,
		size_t	len,
		int	flags,
		sockaddr *	from,
		socklen_t *	fromlen
	)

static

Abstraction for BSD sockets recvfrom(2). This function should emulate its namesake system call exactly.

Parameters

fd	This version of the call takes an EventHandler instead of a bare file descriptor.
buf	The buffer in which the data that is read is stored.
len	The size of the buffer.
flags	A flag value that controls the reception of the data.
from	The remote IP address and port.
fromlen	The size of the from parameter.

Returns: This method should return exactly the same values as the system call it emulates.

◆ Send()

int SocketEngine::Send	(	EventHandler *	fd,
		const void *	buf,
		size_t	len,
		int	flags
	)

static

Abstraction for BSD sockets send(2). This function should emulate its namesake system call exactly.

Parameters

fd	This version of the call takes an EventHandler instead of a bare file descriptor.
buf	The buffer in which the data that is sent is stored.
len	The size of the buffer.
flags	A flag value that controls the sending of the data.

Returns: This method should return exactly the same values as the system call it emulates.

◆ SendTo()

int SocketEngine::SendTo	(	EventHandler *	fd,
		const void *	buf,
		size_t	len,
		int	flags,
		const irc::sockets::sockaddrs &	address
	)

static

Abstraction for BSD sockets sendto(2). This function should emulate its namesake system call exactly.

Parameters

fd	This version of the call takes an EventHandler instead of a bare file descriptor.
buf	The buffer in which the data that is sent is stored.
len	The size of the buffer.
flags	A flag value that controls the sending of the data.
address	The remote IP address and port.

Returns: This method should return exactly the same values as the system call it emulates.

◆ SetReuse()

void SocketEngine::SetReuse ( int sockfd )

static

Set SO_REUSEADDR and SO_LINGER on this file descriptor

◆ Shutdown() [1/2]

int SocketEngine::Shutdown	(	EventHandler *	fd,
		int	how
	)

static

Abstraction for BSD sockets shutdown(2). This function should emulate its namesake system call exactly.

Parameters

fd	This version of the call takes an EventHandler instead of a bare file descriptor.
how	What part of the socket to shut down

Returns: This method should return exactly the same values as the system call it emulates.

◆ Shutdown() [2/2]

int SocketEngine::Shutdown	(	int	fd,
		int	how
	)

static

Abstraction for BSD sockets shutdown(2). This function should emulate its namesake system call exactly.

Returns: This method should return exactly the same values as the system call it emulates.

◆ WriteV()

int SocketEngine::WriteV	(	EventHandler *	fd,
		const IOVector *	iov,
		int	count
	)

static

Abstraction for vector write function writev(). This function should emulate its namesake system call exactly.

Parameters

fd	EventHandler to send data with
iov	Array of IOVectors containing the buffers to send and their lengths in the platform's native format.
count	Number of elements in iov.

Returns: This method should return exactly the same values as the system call it emulates.

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

include/socketengine.h
src/socketengine.cpp
src/socketengines/socketengine_epoll.cpp
src/socketengines/socketengine_kqueue.cpp
src/socketengines/socketengine_poll.cpp
src/socketengines/socketengine_select.cpp

Classes

Public Types

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ Accept()

◆ AddFd()

◆ Bind()

◆ Blocking()

◆ BoundsCheckFd()

◆ ChangeEventMask()

◆ Close() [1/2]

◆ Close() [2/2]

◆ Connect()

◆ Deinit()

◆ DelFd()

◆ DispatchEvents()

◆ DispatchTrialWrites()

◆ GetError()

◆ GetMaxFds()

◆ GetRef()

◆ GetStats()

◆ GetUsedFds()

◆ HasFd()

◆ IgnoreError()

◆ Init()

◆ LastError()

◆ Listen()

◆ NonBlocking()

◆ RecoverFromFork()

◆ Recv()

◆ RecvFrom()

◆ Send()

◆ SendTo()

◆ SetReuse()

◆ Shutdown() [1/2]

◆ Shutdown() [2/2]

◆ WriteV()