tamer::fd Class Reference

A file descriptor wrapper with event-based access functions. More...

#include <tamer/fd.hh>

List of all members.

Public Types

enum  { default_backlog = 128 }
typedef fdimp *fd::* unspecified_bool_type

Public Member Functions

 fd ()
 Default constructor creates an invalid file descriptor.
 fd (int f)
 Creates a wrapper for the file descriptor f.
 fd (const fd &f)
 Construct another wrapper for file descriptor f.
 ~fd ()
 Destroy the file descriptor wrapper.
bool valid () const
 Test if file descriptor is valid.
 operator unspecified_bool_type () const
 Test if file descriptor is valid.
bool operator! () const
 Test if file descriptor is invalid.
int error () const
 Check for file descriptor error.
int value () const
 Return file descriptor value.
void at_close (event<> e)
 Register a close notifier.
event closer ()
 Return a closer event.
void fstat (struct stat &stat, event< int > done)
 Fetch file status.
int listen (int backlog=default_backlog)
 Set socket file descriptor for listening.
int bind (const struct sockaddr *addr, socklen_t addrlen)
 Bind socket file descriptor to local address.
void accept (struct sockaddr *addr, socklen_t *addrlen, event< fd > result)
 Accept new connection on listening socket file descriptor.
void accept (const event< fd > &result)
 Accept new connection on listening socket file descriptor.
void connect (const struct sockaddr *addr, socklen_t addrlen, event< int > done)
 Connect socket file descriptor.
void read (void *buf, size_t size, size_t &nread, event< int > done)
 Read from file descriptor.
void read (void *buf, size_t size, const event< int > &done)
 Read from file descriptor.
void write (const void *buf, size_t size, size_t &nwritten, event< int > done)
 Write to file descriptor.
void write (const void *buf, size_t size, const event< int > &done)
 Write to file descriptor.
void write (std::string buf, size_t &nwritten, event< int > done)
 Write string to file descriptor.
void write (const std::string &buf, const event< int > &done)
 Write string to file descriptor.
void close (event< int > done)
 Close file descriptor.
void close ()
 Close file descriptor.
void error_close (int errcode)
 Close file descriptor, marking it with an error.
fdoperator= (const fd &f)
 Assign this file descriptor to refer to f.

Static Public Member Functions

static int make_nonblocking (int f)
 Make a file descriptor use nonblocking I/O.
static void open (const char *filename, int flags, mode_t mode, event< fd > result)
 Open a file descriptor.
static void open (const char *filename, int flags, event< fd > result)
 Open a file descriptor.
static fd socket (int domain, int type, int protocol)
 Create a socket file descriptor.

Friends

bool operator== (const fd &, const fd &)
 Test whether two file descriptors refer to the same object.
bool operator!= (const fd &, const fd &)
 Test whether two file descriptors refer to the same object.


Detailed Description

A file descriptor wrapper with event-based access functions.

The fd class wraps file descriptors in a convenient interface for Tamer event-based programming. Its methods resemble Unix system calls, but adapted for Tamer events.

fd wrappers are reference-counted and may be freely passed as arguments, copied, assigned, and destroyed. Many fd wrappers may refer to the same underlying file descriptor. This file descriptor is closed when the last wrapper to reference it is destroyed. Alternately, the close() member function explicitly closes the underlying file descriptor.

When a file descriptor is closed, any pending tamer::at_fd_read() and tamer::at_fd_write() events are canceled, and any pending read(), write(), accept(), connect(), and similar pending fd methods will terminate with the -ECANCELED error code (or, equivalently, tamer::outcome::cancel). Any fd methods on a closed file descriptor return the -EBADF error code.

The fd object ensures that reads complete in the order they are called, and similarly for writes. Thus, the following code:

     tamed void greeting(tamer::fd f) {
         tvars {
             int ret;
         }
         twait {
             f.write("Hello, ", make_event(ret));
             f.write("world", make_event(ret));
             f.write("!", make_event(ret));
         }
     }

will always output "<code>Hello, world!</code>", even though the three f.write() calls hypothetically happen in parallel.


Constructor & Destructor Documentation

tamer::fd::fd (  )  [inline]

Default constructor creates an invalid file descriptor.

The resulting file descriptor returns an error() of -EBADF. This error code is also returned by any file descriptor operation.

tamer::fd::fd ( int  f  )  [inline, explicit]

Creates a wrapper for the file descriptor f.

Parameters:
f File descriptor value.
Somewhat like the stdio fdopen() function, this constructor takes control of its file descriptor argument. In particular, when the last reference to the resulting object is destroyed, f is closed automatically.

f may be a negative error code, in which case error() will return the given value.

tamer::fd::fd ( const fd f  )  [inline]

Construct another wrapper for file descriptor f.

Parameters:
f Source file descriptor.
The resulting object and the argument f both refer to the same file descriptor. The underlying file descriptor is reference counted, and will not be automatically destroyed until both f and the resulting object go out of scope.

tamer::fd::~fd (  )  [inline]

Destroy the file descriptor wrapper.

Note:
The underlying file descriptor is closed if this was the last remaining wrapper.


Member Function Documentation

static int tamer::fd::make_nonblocking ( int  f  )  [static]

Make a file descriptor use nonblocking I/O.

Parameters:
f File descriptor value.
Note:
This function's argument is a file descriptor value, not an fd wrapper object. Particularly useful for e.g. standard input.

static void tamer::fd::open ( const char *  filename,
int  flags,
mode_t  mode,
event< fd result 
) [static]

Open a file descriptor.

Parameters:
filename File name.
flags Open flags (O_RDONLY, O_EXCL, and so forth).
mode Permissions mode (used when creating a file).
result Event triggered on completion.
Opens a file descriptor for the named file, returning it via the result event. The returned file descriptor is made nonblocking. To check whether the open succeeded, use valid() or error() on the resulting file descriptor.

See also:
open(const char *, int, event<fd>)

void tamer::fd::open ( const char *  filename,
int  flags,
event< fd result 
) [inline, static]

Open a file descriptor.

Parameters:
filename File name.
flags Open flags (O_RDONLY, O_EXCL, and so forth).
result Event triggered on completion.
Like open(const char *, int, mode_t, event<fd>), passing 0777 for the mode argument.

See also:
open(const char *, int, mode_t, event<fd>)

static fd tamer::fd::socket ( int  domain,
int  type,
int  protocol 
) [static]

Create a socket file descriptor.

Parameters:
domain Socket domain.
type Socket type.
protocol Socket protocol.
The returned socket is made nonblocking. Use valid() or error() to check for errors.

bool tamer::fd::valid (  )  const [inline]

Test if file descriptor is valid.

Returns:
True if file descriptor is valid, false if not.

tamer::fd::operator unspecified_bool_type (  )  const [inline]

Test if file descriptor is valid.

Returns:
True if file descriptor is valid, false if not.

bool tamer::fd::operator! (  )  const [inline]

Test if file descriptor is invalid.

Returns:
False if file descriptor is valid, true if not.

int tamer::fd::error (  )  const [inline]

Check for file descriptor error.

Returns:
0 if file descriptor is valid, otherwise a negative error code.

int tamer::fd::value (  )  const [inline]

Return file descriptor value.

Returns:
File descriptor value if file descriptor is valid, otherwise a negative error code.

void tamer::fd::at_close ( event<>  e  )  [inline]

Register a close notifier.

Parameters:
e Close notifier.
If this file descriptor is invalid, triggers e immediately. Otherwise, triggers e when this file descriptor is closed (either by an explicit close() or as a result of file descriptor references going out of scope).

event tamer::fd::closer (  ) 

Return a closer event.

Returns:
Closer event.
Triggering the returned event will immediately close the file descriptor. Returns an empty event if the file descriptor is invalid.

void tamer::fd::fstat ( struct stat &  stat,
event< int >  done 
)

Fetch file status.

Parameters:
[out] stat Status structure.
done Event triggered on completion.
done is triggered with 0 on success, or a negative error code.

int tamer::fd::listen ( int  backlog = default_backlog  ) 

Set socket file descriptor for listening.

Parameters:
backlog Maximum length of pending connection queue.
Returns 0 on success, or a negative error code.

See also:
tamer::fdx::tcp_listen

int tamer::fd::bind ( const struct sockaddr *  addr,
socklen_t  addrlen 
)

Bind socket file descriptor to local address.

Parameters:
addr Local socket address.
addrlen Length of local socket address.
Returns 0 on success, or a negative error code.

void tamer::fd::accept ( struct sockaddr *  addr,
socklen_t *  addrlen,
event< fd result 
) [inline]

Accept new connection on listening socket file descriptor.

Parameters:
[out] addr Socket address of connecting client.
[in,out] addrlen Length of addr.
result Event triggered on completion.
Accepts a new connection on a listening socket, returning it via the result event. The returned file descriptor is made nonblocking. To check whether the accept succeeded, use valid() or error() on the resulting file descriptor.

If addr is not null, it is filled in with the connecting client's address. On input, addrlen should equal the space available for addr; on output, it is set to the space used for addr.

See also:
accept(const event<fd> &)

void tamer::fd::accept ( const event< fd > &  result  )  [inline]

Accept new connection on listening socket file descriptor.

Parameters:
result Event triggered on completion.
Equivalent to accept(NULL, NULL, result).

void tamer::fd::connect ( const struct sockaddr *  addr,
socklen_t  addrlen,
event< int >  done 
) [inline]

Connect socket file descriptor.

Parameters:
addr Remote address.
addrlen Length of remote address.
done Event triggered on completion.
done is triggered with 0 on success, or a negative error code.

See also:
tamer::fdx::tcp_connect

void tamer::fd::read ( void *  buf,
size_t  size,
size_t &  nread,
event< int >  done 
) [inline]

Read from file descriptor.

Parameters:
[out] buf Buffer.
size Buffer size.
[out] nread Number of characters read.
done Event triggered on completion.
done is triggered with 0 on success or end-of-file, or a negative error code. nread is kept up to date as the read progresses.

void tamer::fd::read ( void *  buf,
size_t  size,
const event< int > &  done 
) [inline]

Read from file descriptor.

Parameters:
[out] buf Buffer.
size Buffer size.
done Event triggered on completion.
Similar to read(void *, size_t, size_t &, event<int>), but does not return the number of characters actually read.

void tamer::fd::write ( const void *  buf,
size_t  size,
size_t &  nwritten,
event< int >  done 
) [inline]

Write to file descriptor.

Parameters:
buf Buffer.
size Buffer size.
[out] nwritten Number of characters written.
done Event triggered on completion.
done is triggered with 0 on success or end-of-file, or a negative error code. nwritten is kept up to date as the write progresses.

See also:
write(std::string, size_t, event<int>)

void tamer::fd::write ( const void *  buf,
size_t  size,
const event< int > &  done 
) [inline]

Write to file descriptor.

Parameters:
buf Buffer.
size Buffer size.
done Event triggered on completion.
Similar to write(const void *, size_t, size_t &, event<int>), but does not return the number of characters actually written.

void tamer::fd::write ( std::string  buf,
size_t &  nwritten,
event< int >  done 
) [inline]

Write string to file descriptor.

Parameters:
buf Buffer.
[out] nwritten Number of characters written.
done Event triggered on completion.
Equivalent to write(buf.data(), buf.length(), nwritten, done).

void tamer::fd::write ( const std::string &  buf,
const event< int > &  done 
) [inline]

Write string to file descriptor.

Parameters:
buf Buffer.
done Event triggered on completion.
Equivalent to write(buf.data(), buf.length(), done).

void tamer::fd::close ( event< int >  done  ) 

Close file descriptor.

Parameters:
done Event triggered on completion.
done is triggered with 0 on success, or a negative error code.

void tamer::fd::close (  )  [inline]

Close file descriptor.

Equivalent to close(event<int>()).

void tamer::fd::error_close ( int  errcode  )  [inline]

Close file descriptor, marking it with an error.

Parameters:
errcode Negative error code.
After error_close(errcode), the valid() function will return false, and error() will return errcode.

fd & tamer::fd::operator= ( const fd f  )  [inline]

Assign this file descriptor to refer to f.

Parameters:
f Source file descriptor.


Friends And Related Function Documentation

bool operator== ( const fd a,
const fd b 
) [friend]

Test whether two file descriptors refer to the same object.

Parameters:
a First file descriptor.
b Second file descriptor.
Returns:
True iff a and b refer to the same file descriptor.

bool operator!= ( const fd a,
const fd b 
) [friend]

Test whether two file descriptors refer to the same object.

Parameters:
a First file descriptor.
b Second file descriptor.
Returns:
True iff a and b do not refer to the same file descriptor.


The documentation for this class was generated from the following file:
Generated on Wed Aug 22 17:55:29 2007 for Tamer by  doxygen 1.5.1