- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Classes | Public Types | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
GNet::Socket Class Reference

The Socket class encapsulates a non-blocking Unix socket file descriptor or a Windows 'SOCKET' handle. More...

`#include <gsocket.h>`

Inheritance diagram for GNet::Socket:

## Classes
class | Credentials
| A credentials class that allows SocketProtocol to call Socket::fd(). More...

## Public Types
typedef size_t | size_type
typedef ssize_t | ssize_type

## Public Member Functions
virtual | ~Socket ()
| Destructor. More...
bool | valid () const
| Returns true if the socket handle is valid (open). More...
std::pair< bool, Address > | getLocalAddress () const
| Retrieves local address of the socket. More...
std::pair< bool, Address > | getPeerAddress () const
| Retrieves address of socket's peer. More...
bool | hasPeer () const
| Returns true if the socket has a valid peer. More...
bool | bind (const Address &address)
| Binds the socket with an INADDR_ANY network address and the port number taken from the given address. More...
bool | canBindHint (const Address &address)
| Returns true if the socket can probably be bound with the given address. More...
bool | connect (const Address &addr, bool *done=NULL)
| Initiates a connection to (or association with) the given address. More...
bool | listen (int backlog=1)
| Starts the socket listening on the bound address for incoming connections or incoming datagrams. More...
virtual ssize_type | write (const char *buf, size_type len)
| Sends data. More...
bool | eWouldBlock ()
| Returns true if the previous socket operation failed with the EWOULDBLOCK or EGAIN error status. More...
bool | eInProgress ()
| Returns true if the previous socket operation failed with the EINPROGRESS error status. More...
bool | eMsgSize ()
| Returns true if the previous socket operation failed with the EMSGSIZE error status. More...
void | addReadHandler (EventHandler &handler)
| Adds this socket to the event source list so that the given handler receives read events. More...
void | dropReadHandler ()
| Reverses addReadHandler(). More...
void | addWriteHandler (EventHandler &handler)
| Adds this socket to the event source list so that the given handler receives write events when flow control is released. More...
void | dropWriteHandler ()
| Reverses addWriteHandler(). More...
void | addExceptionHandler (EventHandler &handler)
| Adds this socket to the event source list so that the given handler receives exception events. More...
void | dropExceptionHandler ()
| Reverses addExceptionHandler(). More...
std::string | asString () const
| Returns the socket handle as a string. More...
std::string | reasonString () const
| Returns the failure reason as a string. More...
void | shutdown (bool for_writing=true)
| Shuts the socket for writing (or reading). More...
int | fd (Credentials) const
| Returns the socket descriptor as an integer. More...

## Protected Member Functions
| Socket (int domain, int type, int protocol)
| Constructor used by derived classes. More...
| Socket (Descriptor s)
| Constructor which creates a socket object from an existing socket handle. More...
void | prepare ()
void | setFault ()
void | setNoLinger ()
void | setReuse ()
void | setKeepAlive ()
std::pair< bool, Address > | getAddress (bool) const

## Static Protected Member Functions
static bool | valid (Descriptor s)
static int | reason ()
static bool | error (int rc)
static bool | sizeError (ssize_type size)

## Protected Attributes
int | m_reason
Descriptor | m_socket

## Detailed Description

The Socket class encapsulates a non-blocking Unix socket file descriptor or a Windows 'SOCKET' handle.

(Non-blocking network i/o is particularly appropriate for single- threaded server processes which manage multiple client connections. The main disagvantage is that flow control has to be managed explicitly: see Socket::write() and Socket::eWouldBlock().)

Provides bind(), listen(), connect(), write(); derived classes provide accept() and read(). Also interfaces to the event loop with addReadHandler() and addWriteHandler().

The raw file descriptor is only exposed to the SocketProtocol class (using the credentials pattern) and to the event loop.

Exceptions are not used.

Definition at line 60 of file gsocket.h.

## Member Typedef Documentation

typedef size_t GNet::Socket::size_type

Definition at line 63 of file gsocket.h.

typedef ssize_t GNet::Socket::ssize_type

Definition at line 64 of file gsocket.h.

## Constructor & Destructor Documentation

GNet::Socket::~Socket | ( |  | ) |
| virtual

Destructor.

Definition at line 65 of file gsocket.cpp.

References G_ASSERT.

GNet::Socket::Socket | ( | int | domain,
|  | int | type,
|  | int | protocol
| ) |  |
| protected

Constructor used by derived classes.

Opens the socket using socket().

Definition at line 31 of file gsocket.cpp.

References G_DEBUG, m_reason, m_socket, prepare(), reason(), and valid().

GNet::Socket::Socket | ( | Descriptor | s | ) |
| explicit protected

Constructor which creates a socket object from an existing socket handle.

Used only by StreamSocket::accept().

Definition at line 46 of file gsocket.cpp.

References prepare().

## Member Function Documentation

void GNet::Socket::addExceptionHandler | ( | EventHandler & | handler | ) |

Adds this socket to the event source list so that the given handler receives exception events.

A TCP exception event should be treated as a disconnection event. (Not used for datagram sockets.)

Definition at line 270 of file gsocket.cpp.

References GNet::EventLoop::addException(), G_ASSERT, G_DEBUG, and GNet::EventLoop::instance().

void GNet::Socket::addReadHandler | ( | EventHandler & | handler | ) |

Adds this socket to the event source list so that the given handler receives read events.

Definition at line 251 of file gsocket.cpp.

References GNet::EventLoop::addRead(), G_ASSERT, G_DEBUG, and GNet::EventLoop::instance().

void GNet::Socket::addWriteHandler | ( | EventHandler & | handler | ) |

Adds this socket to the event source list so that the given handler receives write events when flow control is released.

(Not used for datagram sockets.)

Definition at line 263 of file gsocket.cpp.

References GNet::EventLoop::addWrite(), G_ASSERT, G_DEBUG, and GNet::EventLoop::instance().

std::string GNet::Socket::asString | ( |  | ) | const

Returns the socket handle as a string.

Only used in debugging.

Definition at line 287 of file gsocket.cpp.

bool GNet::Socket::bind | ( | const Address & | address | ) |

Binds the socket with an INADDR_ANY network address and the port number taken from the given address.

This is used for listening sockets.

Definition at line 97 of file gsocket.cpp.

References GNet::Address::address(), GNet::Address::displayString(), G_DEBUG, G_WARNING, and GNet::Address::length().

bool GNet::Socket::canBindHint | ( | const Address & | address | ) |

Returns true if the socket can probably be bound with the given address.

Some implementations will always return true. This method should be used on a temporary socket of the correct dynamic type since this socket may become unusable.

Definition at line 100 of file gsocket_unix.cpp.

Referenced by GNet::Server::canBind().

bool GNet::Socket::connect | ( | const Address & | addr,
|  | bool * | done = `NULL`
| ) |  |

Initiates a connection to (or association with) the given address.

Returns false on error.

If successful, a 'done' flag is returned by reference indicating whether the connect completed immediately. Normally a stream socket connection will take some time to complete so the 'done' flag will be false: the completion will be indicated by a write event some time later.

For datagram sockets this sets up an association between two addresses. The socket should first be bound with a local address.

Definition at line 130 of file gsocket.cpp.

References GNet::Address::address(), GNet::Address::displayString(), G::Test::enabled(), G_DEBUG, and GNet::Address::length().

void GNet::Socket::dropExceptionHandler | ( |  | ) |

Reverses addExceptionHandler().

Definition at line 282 of file gsocket.cpp.

References GNet::EventLoop::dropException(), and GNet::EventLoop::instance().

void GNet::Socket::dropReadHandler | ( |  | ) |

Reverses addReadHandler().

Definition at line 258 of file gsocket.cpp.

References GNet::EventLoop::dropRead(), and GNet::EventLoop::instance().

void GNet::Socket::dropWriteHandler | ( |  | ) |

Reverses addWriteHandler().

Definition at line 277 of file gsocket.cpp.

References GNet::EventLoop::dropWrite(), and GNet::EventLoop::instance().

bool GNet::Socket::eInProgress | ( |  | ) |

Returns true if the previous socket operation failed with the EINPROGRESS error status.

When connecting this can be considered a non-error.

Definition at line 85 of file gsocket_unix.cpp.

bool GNet::Socket::eMsgSize | ( |  | ) |

Returns true if the previous socket operation failed with the EMSGSIZE error status.

When writing to a datagram socket this indicates that the message was too big to send atomically.

Definition at line 90 of file gsocket_unix.cpp.

bool GNet::Socket::error | ( | int | rc | ) |
| static protected

Definition at line 70 of file gsocket_unix.cpp.

bool GNet::Socket::eWouldBlock | ( |  | ) |

Returns true if the previous socket operation failed with the EWOULDBLOCK or EGAIN error status.

When writing this indicates a flow control problem; when reading it indicates that there is nothing to read.

Definition at line 80 of file gsocket_unix.cpp.

int GNet::Socket::fd | ( | Credentials |  | ) | const

Returns the socket descriptor as an integer.

Only callable from SocketProtocol.

Definition at line 306 of file gsocket.cpp.

std::pair< bool, GNet::Address > GNet::Socket::getAddress | ( | bool | local | ) | const
| protected

Definition at line 214 of file gsocket.cpp.

References GNet::Address::invalidAddress(), GNet::AddressStorage::p1(), and GNet::AddressStorage::p2().

std::pair< bool, GNet::Address > GNet::Socket::getLocalAddress | ( |  | ) | const

Retrieves local address of the socket.

Pair.first is false on error.

Definition at line 236 of file gsocket.cpp.

std::pair< bool, GNet::Address > GNet::Socket::getPeerAddress | ( |  | ) | const

Retrieves address of socket's peer.

'Pair.first' is false on error.

Definition at line 241 of file gsocket.cpp.

bool GNet::Socket::hasPeer | ( |  | ) | const

Returns true if the socket has a valid peer.

This can be used to see if a connect succeeded.

Definition at line 246 of file gsocket.cpp.

bool GNet::Socket::listen | ( | int | backlog = `1` | ) |

Starts the socket listening on the bound address for incoming connections or incoming datagrams.

Definition at line 203 of file gsocket.cpp.

void GNet::Socket::prepare | ( |  | ) |
| protected

Definition at line 53 of file gsocket.cpp.

References G_ASSERT, G_WARNING, and G::Cleanup::init().

Referenced by Socket().

int GNet::Socket::reason | ( |  | ) |
| static protected

Definition at line 56 of file gsocket_unix.cpp.

References G_DEBUG.

Referenced by Socket().

std::string GNet::Socket::reasonString | ( |  | ) | const

Returns the failure reason as a string.

Only used in debugging.

Definition at line 294 of file gsocket.cpp.

void GNet::Socket::setFault | ( |  | ) |
| protected

Definition at line 95 of file gsocket_unix.cpp.

void GNet::Socket::setKeepAlive | ( |  | ) |
| protected

Definition at line 189 of file gsocket.cpp.

Referenced by GNet::StreamSocket::StreamSocket().

void GNet::Socket::setNoLinger | ( |  | ) |
| protected

Definition at line 179 of file gsocket.cpp.

Referenced by GNet::StreamSocket::StreamSocket().

void GNet::Socket::setReuse | ( |  | ) |
| protected

Definition at line 196 of file gsocket.cpp.

void GNet::Socket::shutdown | ( | bool | for_writing = `true` | ) |

Shuts the socket for writing (or reading).

Definition at line 301 of file gsocket.cpp.

bool GNet::Socket::sizeError | ( | ssize_type | size | ) |
| static protected

Definition at line 75 of file gsocket_unix.cpp.

bool GNet::Socket::valid | ( |  | ) | const

Returns true if the socket handle is valid (open).

Definition at line 92 of file gsocket.cpp.

Referenced by Socket().

bool GNet::Socket::valid | ( | Descriptor | s | ) |
| static protected

Definition at line 33 of file gsocket_unix.cpp.

References GNet::Descriptor::valid().

GNet::Socket::ssize_type GNet::Socket::write | ( | const char * | buf,
|  | size_type | len
| ) |  |
| virtual

Sends data.

For datagram sockets the datagram is sent to the address specified in the previous connect(). Returns the amount of data submitted.

If write() returns -1 then use eWouldBlock() to determine whether there was a flow control problem. If write() returns -1 and eWouldBlock() returns false then the connection is lost and the socket should be closed. If write() returns less than 'len' then assume that there was a partial flow control problem (do not use eWouldBlock()).

This method is virtual to allow overloading (sic) in derived classes.

Reimplemented in GNet::DatagramSocket.

Definition at line 159 of file gsocket.cpp.

References G_DEBUG, and G_WARNING.

Referenced by GNet::DatagramSocket::write().

## Member Data Documentation

int GNet::Socket::m_reason
| protected

Definition at line 230 of file gsocket.h.

Referenced by Socket().

Descriptor GNet::Socket::m_socket
| protected

Definition at line 231 of file gsocket.h.

Referenced by Socket().

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

- gsocket.h
- gsocket.cpp
- gsocket_unix.cpp