oasys::Notifier Class Reference

#include <Notifier.h>

Inheritance diagram for oasys::Notifier:

oasys::Logger oasys::MsgQueue< _elt_t >

List of all members.


Detailed Description

Thread notification abstraction that wraps an underlying pipe.

This can be used as a generic abstraction to pass messages between threads.

A call to notify() sends a byte down the pipe, while calling wait() causes the thread to block in poll() waiting for some data to be sent on the pipe.

In addition, through read_fd() a thread can get the file descriptor to explicitly block on while awaiting notification. In that case, the calling thread should explicitly call drain_pipe().

Definition at line 41 of file Notifier.h.


Public Member Functions

 Notifier (const char *logpath, bool keep_quiet=false)
 Constructor that takes the logging path and an optional boolean to suppress all logging.
 ~Notifier ()
 Destructor.
bool wait (SpinLock *lock=NULL, int timeout=-1, bool drain_the_pipe=true)
 Block the calling thread, pending a call to notify().
void notify (SpinLock *lock=NULL)
 Notify a waiter.
void drain_pipe (size_t bytes)
 
Parameters:
bytes Drain this many bytes from the pipe.

int read_fd ()
 The read side of the pipe, suitable for an explicit call to poll().
int write_fd ()
 The write side of the pipe.

Protected Attributes

bool waiter_
int count_
int pipe_ [2]
bool quiet_
atomic_t busy_notifiers_

Constructor & Destructor Documentation

oasys::Notifier::Notifier ( const char *  logpath,
bool  keep_quiet = false 
)

Constructor that takes the logging path and an optional boolean to suppress all logging.

Definition at line 27 of file Notifier.cc.

References errno, log_debug, oasys::Logger::logpath_, oasys::Logger::logpath_appendf(), pipe_, quiet_, oasys::IO::set_nonblocking(), and waiter_.

oasys::Notifier::~Notifier (  ) 

Destructor.

Definition at line 54 of file Notifier.cc.

References oasys::atomic_cmpxchg32(), busy_notifiers_, errno, log_debug, log_err, pipe_, and quiet_.


Member Function Documentation

bool oasys::Notifier::wait ( SpinLock lock = NULL,
int  timeout = -1,
bool  drain_the_pipe = true 
)

Block the calling thread, pending a call to notify().

If a lock is passed in, wait() will unlock the lock before the thread blocks and re-take it when the thread unblocks. If a timeout is specified, only wait for that amount of time.

Returns true if the thread was notified, false if a timeout occurred.

Definition at line 146 of file Notifier.cc.

References count_, drain_pipe(), errno, oasys::IOTIMEOUT, oasys::SpinLock::lock(), log_debug, oasys::Logger::logpath_, oasys::IO::poll_single(), quiet_, read_fd(), oasys::SpinLock::unlock(), and waiter_.

Referenced by dtn::BlockingBundleList::pop_blocking(), dtn::BundleDaemon::post_and_wait(), and dtn::BluetoothDiscovery::run().

void oasys::Notifier::notify ( SpinLock lock = NULL  ) 

Notify a waiter.

In general, this function should not block, but there's a chance that it might if the pipe ends up full. In that case, it will unlock the given lock (if any) and will block until the notification ends up in the pipe.

Definition at line 191 of file Notifier.cc.

References ASSERT, oasys::atomic_decr(), oasys::atomic_incr(), busy_notifiers_, count_, errno, oasys::SpinLock::lock(), log_debug, log_err, log_warn, quiet_, oasys::SpinLock::unlock(), and write_fd().

Referenced by dtn::BundleList::add_bundle(), oasys::IOHandlerBase::interrupt_from_io(), oasys::SMTPHandlerThread::run(), and dtn::BluetoothDiscovery::shutdown().

void oasys::Notifier::drain_pipe ( size_t  bytes  ) 

Parameters:
bytes Drain this many bytes from the pipe.

0 means to drain all of the bytes possible in the pipe. The default is to drain 1 byte. Anything different will probably be a race condition unless there is some kind of locking going on.

Definition at line 91 of file Notifier.cc.

References count_, errno, oasys::IOAGAIN, log_crit, log_debug, log_warn, quiet_, oasys::IO::read(), and read_fd().

Referenced by dtn::BundleList::del_bundle(), oasys::IO::poll_with_notifier(), and wait().

int oasys::Notifier::read_fd (  )  [inline]

The read side of the pipe, suitable for an explicit call to poll().

Definition at line 89 of file Notifier.h.

References pipe_.

Referenced by drain_pipe(), oasys::IO::poll_with_notifier(), dtntunnel::TCPTunnel::Connection::run(), wait(), and dtn::APIClient::wait_for_bundle().

int oasys::Notifier::write_fd (  )  [inline]

The write side of the pipe.

Definition at line 94 of file Notifier.h.

References pipe_.

Referenced by notify().


Member Data Documentation

bool oasys::Notifier::waiter_ [protected]

Definition at line 97 of file Notifier.h.

Referenced by Notifier(), and wait().

int oasys::Notifier::count_ [protected]

Definition at line 98 of file Notifier.h.

Referenced by drain_pipe(), notify(), and wait().

int oasys::Notifier::pipe_[2] [protected]

Definition at line 99 of file Notifier.h.

Referenced by Notifier(), read_fd(), write_fd(), and ~Notifier().

bool oasys::Notifier::quiet_ [protected]

Definition at line 100 of file Notifier.h.

Referenced by drain_pipe(), Notifier(), notify(), wait(), and ~Notifier().

atomic_t oasys::Notifier::busy_notifiers_ [protected]

Definition at line 101 of file Notifier.h.

Referenced by notify(), and ~Notifier().


The documentation for this class was generated from the following files:
Generated on Sat Sep 8 08:36:26 2007 for DTN Reference Implementation by  doxygen 1.5.3