plumbing::endpoint Class Reference

#include <endpoint.h>

Inheritance diagram for plumbing::endpoint:
plumbing::endpoint_client plumbing::endpoint_listener plumbing::endpoint_client_stdout

Public Types

typedef boost::shared_ptr
< endpoint > 		pointer

Public Member Functions

virtual ~endpoint ()
virtual int get_read_file_descriptor ()
virtual int get_write_file_descriptor ()
virtual void process_read ()=0
virtual void process_write ()=0
virtual void process_timeout ()
bool is_ready_to_die () const
virtual time_value get_maximum_sleep () const

Protected Member Functions

 endpoint (int fd)
 endpoint (int fd, const void *sock_addr, int sock_addr_len)
void fatal_error (const char *fmt,...) FORMAT_PRINTF(2
void fatal_error_v (const char *fmt, va_list ap) FORMAT_PRINTF(2
void void warning (const char *fmt,...) FORMAT_PRINTF(2
void void void warning_v (const char *fmt, va_list ap) FORMAT_PRINTF(2
void void void void set_peer_name (const char *name)
void set_peer_name (const std::string &name)
const char * get_peer_name () const
virtual void close ()
void kill_me_now ()

Static Protected Member Functions

void static int parse_port_number (const std::string &text)
static int parse_port_number_or_die (const std::string &text, bool empty_is_ok=false)

Protected Attributes

int fd

Private Member Functions

void set_peer_name ()
void set_peer_name (const void *sock_addr, int sock_addr_len)
 endpoint ()
 endpoint (const endpoint &)
endpoint & operator= (const endpoint &)

Private Attributes

std::string peer_name
bool ready_to_die

Detailed Description

The plumbing::endpoint class is used to represent an object serving a specific client connection, or to represent a clinet's connection to a server; or, more generally, any file descriptor based data source or sink.

When endpoints determine that they are ready to be removed from the reactor's list of endpoints and be destroyed, they shall call the kill_me_now() method. Depending on when they call this, it may be possible that they will still get some methods called, because the reactor only tests for this condition once per loop.

Definition at line 43 of file endpoint.h.

Member Typedef Documentation

typedef boost::shared_ptr<endpoint> plumbing::endpoint::pointer

The pointer type is used to present a pointer to an instance of this class. By defining it here, the pointer semantics can be changed later, in just this one place, and only a recompile is required.

Definition at line 52 of file endpoint.h.

Constructor & Destructor Documentation

virtual plumbing::endpoint::~endpoint (  )  [virtual]

The destructor.

plumbing::endpoint::endpoint ( int  fd  )  [protected]

The constructor. It is protected on purpose, you must derive from this class.

Parameters:
fd The file descriptor of the bi-directional socket for communicating with the client.
plumbing::endpoint::endpoint ( int  fd,
const void *  sock_addr,
int  sock_addr_len 
) [protected]

The constructor. It is protected on purpose, you must derive from this class.

Parameters:
fd The file descriptor of the bi-directional socket for communicating with the client.
sock_addr The socket address to use. Note that it is really of type sockaddr, but it's void* here so as to avoid unnecessarily sucking in all of the socket machinery includes.
sock_addr_len The length of the socket address data.
plumbing::endpoint::endpoint (  )  [private]

The default constructor. Do not use.

plumbing::endpoint::endpoint ( const endpoint &   )  [private]

The copy constructor. Do not use.

Member Function Documentation

virtual void plumbing::endpoint::close (  )  [protected, virtual]

The close method is used to close the file descriptor associated with this end point. This endpointer will be pretty much useless after that.

void plumbing::endpoint::fatal_error ( const char *  fmt,
  ... 
) [protected]

The fatal_error method is used to report fatal errors, and then terminate via exit(2).

Parameters:
fmt The format string describing the rest of the arguments. See printf(3) for more information.
void plumbing::endpoint::fatal_error_v ( const char *  fmt,
va_list  ap 
) [protected]

The fatal_error_v method is used to report fatal errors, and then terminate via exit(2), but it gets its arguments form the given location

Parameters:
fmt The format string describing the rest of the arguments. See vprintf(3) for more information.
ap pointer to the arguments
virtual time_value plumbing::endpoint::get_maximum_sleep (  )  const [virtual]

The get_maximum_sleep method is used to determine how long this endpoint is prepared to sleep in the absence of any file descriptor activity.

Derived classes can call endpoint::get_maximum_sleep() if they need an "infinity" value. (The default "ininity" is 60 seconds.)

const char* plumbing::endpoint::get_peer_name (  )  const [inline, protected]

The get_peer_name method may be used to obtain the name of the endpoint (the other end, in the case of network sockets). This is most often used for error messages.

Definition at line 284 of file endpoint.h.

virtual int plumbing::endpoint::get_read_file_descriptor (  )  [virtual]

The get_read_file_descriptor method is used to obtain the file descriptor that select is to wait upon for read events. The default implementation returns the fd instance variable.

Returns:
int; >=0 for a valid file descriptior, or -1 if read events should not be waited for.
Note:
DO NOT close the file descriptor and set it to -1 in this method. Do that in the process_read method instead, otherwise you confuse the select() processing.

Reimplemented in plumbing::endpoint_client, and plumbing::endpoint_listener.

virtual int plumbing::endpoint::get_write_file_descriptor (  )  [virtual]

The get_write_file_descriptor method is used to obtain the file descriptor that select is to wait upon for write events. The default implementation returns -1.

Returns:
int; >=0 for a valid file descriptior, or -1 if write events should not be waited for.
Note:
This method need not returns the same file descriptor as returned by the get_read_file_descriptor method. You could, for example, use dup(2) to separate the two.
DO NOT close the file descriptor and set it to -1 in this method. Do that in the process_write method instead, otherwise you confuse the select() processing.

Reimplemented in plumbing::endpoint_client.

bool plumbing::endpoint::is_ready_to_die (  )  const

The is_ready_to_die method is used by the reactor to determine whether or not this endpoint should be removed from the reactor's list of endpoints and destroyed.

void plumbing::endpoint::kill_me_now (  )  [protected]

The kill_me_now method is used by endpoints when they are ready to be removed from the reactor's list of endpoints and be destroyed.

endpoint& plumbing::endpoint::operator= ( const endpoint &   )  [private]

The assignment operator. Do not use.

void static int plumbing::endpoint::parse_port_number ( const std::string &  text  )  [static, protected]

The parse_port_number class method is used to translate a textual representation of a port number into an interger.

Parameters:
text The port name (e.g. "ssh") or number (e.g. "22").
Returns:
the port number (1..65525), or -1 on error.
static int plumbing::endpoint::parse_port_number_or_die ( const std::string &  text,
bool  empty_is_ok = false 
) [static, protected]

The parse_port_number_or_die class method is used to translate a textual representation of a port number into an interger. If it fails, it exits via the log().fatal_error() method.

Parameters:
text The port name (e.g. "ssh") or number (e.g. "22").
empty_is_ok This is true if the empty string is acceptable and should return -1. This is false of the empty string is not acceptable and causes a fatal error.
Returns:
On success, the port number (1..65525); or, if it was the empty string and empty is OK, -1. On error, exits via the log().fatal_error() method.
virtual void plumbing::endpoint::process_read (  )  [pure virtual]

The process_read method is called by the select loop when a readable event is detected on the read file descriptor.

Implemented in plumbing::endpoint_client, and plumbing::endpoint_listener.

virtual void plumbing::endpoint::process_timeout (  )  [virtual]

The process timeout method is called by the select loop whenever the select times out without seeing any activity.

To choose your timeout, return the desired time from the get_maximum_sleep method

Note:
It is possible that a derived class's process_timeout method will be called, even when it returns "infinity" from its get_maximum_sleep method. ALL endpoints have their process_timeout method called after select times out.
virtual void plumbing::endpoint::process_write (  )  [pure virtual]

The process_write method is called by the select loop when a writable event is detected on the read file descriptor.

Implemented in plumbing::endpoint_client, and plumbing::endpoint_listener.

void plumbing::endpoint::set_peer_name ( const void *  sock_addr,
int  sock_addr_len 
) [private]

The set_peer_name method may be used to set the peer_name instance variable from the supplied socket address.

Parameters:
sock_addr The socket address to use. Note that it is really of type sockaddr, but it's void* here so avoid unnecessarily sucking in all of the socket machinery includes.
sock_addr_len The length of the socket address data.
void plumbing::endpoint::set_peer_name (  )  [private]

The set_peer_name method may be used to probe the socket to discover the identity of the other end of the connection, and set the peer_name instance variable appropriately.

void plumbing::endpoint::set_peer_name ( const std::string &  name  )  [protected]

The set_peer_name method may be used to set the peer_name instance variable from the supplied string. This method may be called more than once, the lastest value is retained.

Parameters:
name The name of the endpoint (usually the other end, in the case of a network socket).
void void void void plumbing::endpoint::set_peer_name ( const char *  name  )  [protected]

The set_peer_name method may be used to set the peer_name instance variable from the supplied string. This method may be called more than once, the lastest value is retained.

Parameters:
name The name of the endpoint (usually the other end, in the case of a network socket).
void void plumbing::endpoint::warning ( const char *  fmt,
  ... 
) [protected]

The warning method is used to report warnings.

Parameters:
fmt The format string describing the rest of the arguments. See printf(3) for more information.
void void void plumbing::endpoint::warning_v ( const char *  fmt,
va_list  ap 
) [protected]

The warning_v method is used to report warnings, but it gets its arguments form the given location

Parameters:
fmt The format string describing the rest of the arguments. See vprintf(3) for more information.
ap pointer to the arguments

Field Documentation

int plumbing::endpoint::fd [protected]

The fd instance variable is used to remember the file descriptor of the bi-directional socket for communicating with the client.

This instance variable is not private, so that derived classes can manipulate it. In particular, to cope with network connections going up and down, but providing the illusion of continuous service.

Modify this value with extreme care.

Definition at line 181 of file endpoint.h.

std::string plumbing::endpoint::peer_name [private]

The peer_name instance variable is used to remember the name of the other end of the socket. It is used to give more informative error messages.

Definition at line 307 of file endpoint.h.

bool plumbing::endpoint::ready_to_die [private]

The ready_to_die instance variable is used to remember whether or not this endpoint is ready to be removed from the reactor's list of endpoints and destroyed.

Definition at line 314 of file endpoint.h.

The documentation for this class was generated from the following file:
Generated on Thu Sep 16 14:32:12 2010 for Plumbing by  doxygen 1.6.3