dtn::BundleList Class Reference

#include <BundleList.h>

Inheritance diagram for dtn::BundleList:

oasys::Logger dtn::BlockingBundleList List of all members.

Detailed Description

List structure for handling bundles.

All list operations are protected with a spin lock so they are thread safe. In addition, the lock itself is exposed so a routine that needs to perform more complicated functions (like scanning the list) must lock the list before doing so.

NOTE: It is important that no locks be held on any bundles that might be contained within the list when calling list manipulation functions. Doing so could cause a potential deadlock due to a lock ordering violation, as the list manipulation routines first lock the list, and then lock the bundle(s) being added or removed.

The internal data structure is an STL list of Bundle pointers. The list is also derived from Notifier, and the various push() calls will call notify() if there is a thread blocked on an empty list waiting for notification.

List methods also maintain mappings (i.e. "back pointers") in each Bundle instance to the set of lists that contain the bundle.

Lists follow the reference counting rules for bundles. In particular, the push*() methods increment the reference count, and erase() decrements it. In particular, the pop() variants (as well as the other accessors) return instances of the BundleRef classes that forces the caller to use the BundleRef classes as well in order to properly maintain the reference counts.

Definition at line 87 of file BundleList.h.

Public Types

enum  sort_order_t { SORT_PRIORITY = 0x1, SORT_FRAG_OFFSET }
 Type codes for sorted insertion. More...
typedef std::list< Bundle * > List
 Type for the list itself.
typedef List::iterator iterator
 Type for an iterator.
typedef List::const_iterator const_iterator
 Type for a const iterator.

Public Member Functions

 BundleList (const std::string &name)
 Constructor.
virtual ~BundleList ()
 Destructor -- clears the list.
BundleRef front ()
 Peek at the first bundle on the list.
BundleRef back ()
 Peek at the last bundle on the list.
void push_front (Bundle *bundle)
 Add a new bundle to the front of the list.
void push_back (Bundle *bundle)
 Add a new bundle to the front of the list.
void insert_sorted (Bundle *bundle, sort_order_t sort_order)
 Insert the given bundle sorted by the given sort method.
void insert_random (Bundle *bundle)
 As a testing hook, insert the given bundle into a random location in the list.
BundleRef pop_front (bool used_notifier=false)
 Remove (and return) the first bundle on the list.
BundleRef pop_back (bool used_notifier=false)
 Remove (and return) the last bundle on the list.
bool erase (Bundle *bundle, bool used_notifier=false)
 Remove the given bundle from the list.
bool contains (Bundle *bundle)
 Search the list for the given bundle.
BundleRef find (u_int32_t bundleid)
 Search the list for a bundle with the given id.
BundleRef find (const EndpointID &source_eid, const BundleTimestamp &creation_ts)
 Search the list for a bundle with the given source eid and timestamp.
void move_contents (BundleList *other)
 Move all bundles from this list to another.
void clear ()
 Clear out the list.
size_t size () const
 Return the size of the list.
iterator begin ()
 Iterator used to iterate through the list.
iterator end ()
 Iterator used to mark the end of the list.
const_iterator begin () const
 Const iterator used to iterate through the list.
const_iterator end () const
 Const iterator used to mark the end of the list.
oasys::SpinLocklock () const
 Return the internal lock on this list.
const std::string & name () const
 Return the identifier name of this list.

Protected Member Functions

void add_bundle (Bundle *bundle, const iterator &pos)
 Helper routine to insert a bundle immediately before the indicated position.
Bundledel_bundle (const iterator &pos, bool used_notifier)
 Helper routine to remove a bundle from the indicated position.

Protected Attributes

std::string name_
oasys::SpinLocklock_
oasys::Notifiernotifier_
List list_


Member Typedef Documentation

typedef std::list<Bundle*> dtn::BundleList::List

Type for the list itself.

Definition at line 92 of file BundleList.h.

typedef List::iterator dtn::BundleList::iterator

Type for an iterator.

Definition at line 97 of file BundleList.h.

typedef List::const_iterator dtn::BundleList::const_iterator

Type for a const iterator.

Definition at line 102 of file BundleList.h.


Member Enumeration Documentation

enum dtn::BundleList::sort_order_t

Type codes for sorted insertion.

Enumerator:
SORT_PRIORITY  Sort by bundle priority.
SORT_FRAG_OFFSET  Sort by fragment offset.

Definition at line 141 of file BundleList.h.


Constructor & Destructor Documentation

dtn::BundleList::BundleList ( const std::string &  name  ) 

Constructor.

Definition at line 55 of file BundleList.cc.

dtn::BundleList::~BundleList (  )  [virtual]

Destructor -- clears the list.

Definition at line 61 of file BundleList.cc.

References clear(), and lock_.


Member Function Documentation

BundleRef dtn::BundleList::front (  ) 

Peek at the first bundle on the list.

Returns:
the bundle or NULL if the list is empty

Definition at line 71 of file BundleList.cc.

References ExamineDump::l, list_, and lock_.

BundleRef dtn::BundleList::back (  ) 

Peek at the last bundle on the list.

Returns:
the bundle or NULL if the list is empty

Definition at line 87 of file BundleList.cc.

References ExamineDump::l, list_, and lock_.

void dtn::BundleList::push_front ( Bundle bundle  ) 

Add a new bundle to the front of the list.

Definition at line 131 of file BundleList.cc.

References add_bundle(), ExamineDump::l, list_, dtn::Bundle::lock_, and lock_.

void dtn::BundleList::push_back ( Bundle bundle  ) 

Add a new bundle to the front of the list.

Definition at line 142 of file BundleList.cc.

References add_bundle(), ExamineDump::l, list_, dtn::Bundle::lock_, and lock_.

Referenced by dtn::BundleDaemon::accept_custody(), dtn::BundleDaemon::add_to_pending(), dtn::TclRegistration::deliver_bundle(), dtn::APIRegistration::deliver_bundle(), dtn::FloodBundleRouter::handle_bundle_received(), dtn::BundleDaemon::handle_bundle_received(), dtn::BundleActions::inject_bundle(), and move_contents().

void dtn::BundleList::insert_sorted ( Bundle bundle,
sort_order_t  sort_order 
)

Insert the given bundle sorted by the given sort method.

Definition at line 153 of file BundleList.cc.

References add_bundle(), dtn::Bundle::frag_offset_, ExamineDump::l, list_, dtn::Bundle::lock_, lock_, NOTIMPLEMENTED, SORT_FRAG_OFFSET, and SORT_PRIORITY.

Referenced by dtn::FragmentManager::process_for_reassembly().

void dtn::BundleList::insert_random ( Bundle bundle  ) 

As a testing hook, insert the given bundle into a random location in the list.

Definition at line 191 of file BundleList.cc.

References add_bundle(), begin(), ExamineDump::l, dtn::Bundle::lock_, lock_, log_info, and size().

Referenced by dtn::APIRegistration::deliver_bundle().

BundleRef dtn::BundleList::pop_front ( bool  used_notifier = false  ) 

Remove (and return) the first bundle on the list.

Parameters:
used_notifier Popping off of the BundleList after coming off of a notifier. This will drain one item off of the notifier queue.
Returns:
a reference to the bundle or a reference to NULL if the list is empty.

Definition at line 255 of file BundleList.cc.

References ASSERT, del_bundle(), dtn::Bundle::del_ref(), ExamineDump::l, list_, lock_, and name_.

Referenced by clear(), dtn::TclRegistration::get_bundle_data(), dtn::BundleDaemon::handle_reassembly_completed(), dtn::APIClient::handle_recv(), move_contents(), dtn::BlockingBundleList::pop_blocking(), and dtn::BluetoothConvergenceLayer::Connection::send_loop().

BundleRef dtn::BundleList::pop_back ( bool  used_notifier = false  ) 

Remove (and return) the last bundle on the list.

Note (as explained above) that this does not decrement the bundle reference count.

Parameters:
used_notifier Popping off of the BundleList after coming off of a notifier. This will drain one item off of the notifier queue.
Returns:
a reference to the bundle or a reference to NULL if the list is empty.

Definition at line 278 of file BundleList.cc.

References del_bundle(), ExamineDump::l, list_, lock_, and name_.

bool dtn::BundleList::erase ( Bundle bundle,
bool  used_notifier = false 
)

Remove the given bundle from the list.

Returns true if the bundle was successfully removed, false otherwise.

Unlike the pop() functions, this does remove the list's reference on the bundle.

Definition at line 303 of file BundleList.cc.

References begin(), del_bundle(), dtn::Bundle::del_ref(), end(), oasys::Lock::is_locked_by_me(), ExamineDump::l, lock_, dtn::Bundle::lock_, and name_.

Referenced by dtn::BundleDaemon::delete_from_pending(), dtn::FloodBundleRouter::handle_bundle_expired(), and dtn::BundleDaemon::release_custody().

bool dtn::BundleList::contains ( Bundle bundle  ) 

Search the list for the given bundle.

Returns:
true if found, false if not

Definition at line 331 of file BundleList.cc.

References ASSERT, begin(), end(), dtn::Bundle::is_queued_on(), ExamineDump::l, and lock_.

Referenced by dtn::BundleDaemon::handle_custody_timeout().

BundleRef dtn::BundleList::find ( u_int32_t  bundleid  ) 

Search the list for a bundle with the given id.

Returns:
a reference to the bundle or a reference to NULL if the list is empty.

Definition at line 355 of file BundleList.cc.

References begin(), end(), ExamineDump::l, and lock_.

Referenced by dtn::BundleCommand::exec(), and dtn::BundleDaemon::handle_custody_signal().

BundleRef dtn::BundleList::find ( const EndpointID source_eid,
const BundleTimestamp creation_ts 
)

Search the list for a bundle with the given source eid and timestamp.

Returns:
a reference to the bundle or a reference to NULL if the list is empty.

Definition at line 376 of file BundleList.cc.

References begin(), end(), ExamineDump::l, lock_, dtn::BundleTimestamp::seconds_, and dtn::BundleTimestamp::seqno_.

void dtn::BundleList::move_contents ( BundleList other  ) 

Move all bundles from this list to another.

Definition at line 399 of file BundleList.cc.

References list_, lock_, oasys::Ref< _Type >::object(), pop_front(), and push_back().

Referenced by dtn::ReassemblyCompletedEvent::ReassemblyCompletedEvent().

void dtn::BundleList::clear (  ) 

Clear out the list.

Definition at line 415 of file BundleList.cc.

References ExamineDump::l, list_, lock_, and pop_front().

Referenced by ~BundleList().

size_t dtn::BundleList::size (  )  const

Return the size of the list.

Definition at line 430 of file BundleList.cc.

References ExamineDump::l, list_, and lock_.

Referenced by dtn::BluetoothConvergenceLayer::Connection::break_contact(), dtn::FragmentManager::check_completed(), dtn::BundleCommand::exec(), insert_random(), dtn::FragmentManager::process_for_reassembly(), and dtn::APIClient::wait_for_bundle().

BundleList::iterator dtn::BundleList::begin (  ) 

Iterator used to iterate through the list.

Iterations _must_ be completed while holding the list lock, and this method will assert as such.

Definition at line 442 of file BundleList.cc.

References oasys::Lock::is_locked_by_me(), list_, and lock_.

Referenced by dtn::FragmentManager::check_completed(), dtn::TableBasedRouter::check_next_hop(), contains(), erase(), dtn::BundleCommand::exec(), find(), dtn::BundleDaemon::find_duplicate(), dtn::BundleDaemon::handle_registration_added(), and insert_random().

BundleList::iterator dtn::BundleList::end (  ) 

Iterator used to mark the end of the list.

Iterations _must_ be completed while holding the list lock, and this method will assert as such.

Definition at line 456 of file BundleList.cc.

References oasys::Lock::is_locked_by_me(), list_, and lock_.

Referenced by dtn::FragmentManager::check_completed(), dtn::TableBasedRouter::check_next_hop(), contains(), erase(), dtn::BundleCommand::exec(), find(), dtn::BundleDaemon::find_duplicate(), and dtn::BundleDaemon::handle_registration_added().

BundleList::const_iterator dtn::BundleList::begin (  )  const

Const iterator used to iterate through the list.

Iterations _must_ be completed while holding the list lock, and this method will assert as such.

Definition at line 470 of file BundleList.cc.

References oasys::Lock::is_locked_by_me(), list_, and lock_.

BundleList::const_iterator dtn::BundleList::end (  )  const

Const iterator used to mark the end of the list.

Iterations _must_ be completed while holding the list lock, and this method will assert as such.

Definition at line 485 of file BundleList.cc.

References oasys::Lock::is_locked_by_me(), list_, and lock_.

oasys::SpinLock* dtn::BundleList::lock (  )  const [inline]

Return the internal lock on this list.

Definition at line 264 of file BundleList.h.

References lock_.

Referenced by dtn::FragmentManager::check_completed(), dtn::TableBasedRouter::check_next_hop(), dtn::BundleCommand::exec(), dtn::BundleDaemon::find_duplicate(), and dtn::BundleDaemon::handle_registration_added().

const std::string& dtn::BundleList::name (  )  const [inline]

Return the identifier name of this list.

Definition at line 269 of file BundleList.h.

References name_.

void dtn::BundleList::add_bundle ( Bundle bundle,
const iterator pos 
) [protected]

Helper routine to insert a bundle immediately before the indicated position.

Definition at line 104 of file BundleList.cc.

References dtn::Bundle::add_ref(), ASSERT, dtn::Bundle::bundleid_, oasys::Lock::is_locked_by_me(), list_, dtn::Bundle::lock_, lock_, log_debug, log_err, dtn::Bundle::mappings_, name_, notifier_, and oasys::Notifier::notify().

Referenced by insert_random(), insert_sorted(), push_back(), and push_front().

Bundle * dtn::BundleList::del_bundle ( const iterator pos,
bool  used_notifier 
) [protected]

Helper routine to remove a bundle from the indicated position.

Parameters:
pos Position to delete
used_notifier Popping off of the BundleList after coming off of a notifier. This will drain one item off of the notifier queue.
Returns:
the bundle that, before this call, was at the position

Definition at line 216 of file BundleList.cc.

References ASSERT, dtn::Bundle::bundleid_, oasys::Notifier::drain_pipe(), oasys::Lock::is_locked_by_me(), ExamineDump::l, list_, dtn::Bundle::lock_, lock_, log_debug, log_err, dtn::Bundle::mappings_, name_, and notifier_.

Referenced by erase(), pop_back(), and pop_front().


Member Data Documentation

std::string dtn::BundleList::name_ [protected]

Definition at line 289 of file BundleList.h.

Referenced by add_bundle(), del_bundle(), erase(), name(), pop_back(), dtn::BlockingBundleList::pop_blocking(), and pop_front().

oasys::SpinLock* dtn::BundleList::lock_ [protected]

Definition at line 290 of file BundleList.h.

Referenced by add_bundle(), back(), begin(), clear(), contains(), del_bundle(), end(), erase(), find(), front(), insert_random(), insert_sorted(), lock(), move_contents(), pop_back(), dtn::BlockingBundleList::pop_blocking(), pop_front(), push_back(), push_front(), size(), and ~BundleList().

oasys::Notifier* dtn::BundleList::notifier_ [protected]

Definition at line 291 of file BundleList.h.

Referenced by add_bundle(), dtn::BlockingBundleList::BlockingBundleList(), del_bundle(), dtn::BlockingBundleList::notifier(), dtn::BlockingBundleList::pop_blocking(), and dtn::BlockingBundleList::~BlockingBundleList().

List dtn::BundleList::list_ [protected]

Definition at line 292 of file BundleList.h.

Referenced by add_bundle(), back(), begin(), clear(), del_bundle(), end(), front(), insert_sorted(), move_contents(), pop_back(), dtn::BlockingBundleList::pop_blocking(), pop_front(), push_back(), push_front(), and size().


The documentation for this class was generated from the following files:
Generated on Fri Dec 22 14:48:03 2006 for DTN Reference Implementation by  doxygen 1.5.1