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 66 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) a reference to 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.
void set_name (const std::string &name)
 Set the name (useful for classes that are unserialized).

Protected Member Functions

void add_bundle (Bundle *bundle, const iterator &pos)
 Helper routine to add a bundle at 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 71 of file BundleList.h.

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

Type for an iterator.

Definition at line 76 of file BundleList.h.

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

Type for a const iterator.

Definition at line 81 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 120 of file BundleList.h.


Constructor & Destructor Documentation

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

Constructor.

Definition at line 31 of file BundleList.cc.

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

Destructor -- clears the list.

Definition at line 44 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 54 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 70 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 114 of file BundleList.cc.

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

Referenced by dtn::ProphetEncounter::fwd_to_nexthop().

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

Add a new bundle to the front of the list.

Definition at line 125 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::ProphetBundleQueue::bundle_list(), dtn::TclRegistration::deliver_bundle(), dtn::APIRegistration::deliver_bundle(), dtn::ProphetEncounter::fwd_to_nexthop(), dtn::FloodBundleRouter::handle_bundle_received(), dtn::BundleDaemon::handle_bundle_received(), 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 136 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 174 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) a reference to the first bundle on the list.

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 238 of file BundleList.cc.

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

Referenced by clear(), dtn::ProphetEncounter::fwd_to_nexthop(), dtn::TclRegistration::get_bundle_data(), dtn::BundleDaemon::handle_reassembly_completed(), dtn::APIClient::handle_recv(), move_contents(), and dtn::BlockingBundleList::pop_blocking().

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 261 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 286 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::FragmentManager::delete_fragment(), 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 314 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  bundle_id  ) 

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.

the bundle or NULL if not found.

Definition at line 338 of file BundleList.cc.

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

Referenced by dtn::BundleCommand::exec(), dtn::BundleDaemon::handle_bundle_cancel(), dtn::BundleDaemon::handle_bundle_send(), 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.

the bundle or NULL if not found.

Definition at line 359 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 382 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 398 of file BundleList.cc.

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

Referenced by dtn::ProphetEncounter::handle_bundle_tlv(), and ~BundleList().

size_t dtn::BundleList::size (  )  const

Return the size of the list.

Definition at line 413 of file BundleList.cc.

References ExamineDump::l, list_, and lock_.

Referenced by dtn::ProphetBundleQueue::bundle_list(), dtn::FragmentManager::check_completed(), dtn::FragmentManager::delete_fragment(), dtn::BundleCommand::exec(), dtn::ProphetEncounter::fwd_to_nexthop(), dtn::ProphetEncounter::handle_bundle_tlv(), 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 425 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(), dtn::ProphetBundleList::find(), find(), dtn::BundleDaemon::find_duplicate(), dtn::ProphetEncounter::fwd_to_nexthop(), dtn::BundleDaemon::handle_registration_added(), insert_random(), dtn::ProphetBundleOffer::ProphetBundleOffer(), dtn::ProphetBundleQueue::ProphetBundleQueue(), and dtn::BundleReportEvent::serialize().

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 439 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(), dtn::ProphetBundleList::find(), find(), dtn::BundleDaemon::find_duplicate(), dtn::ProphetEncounter::fwd_to_nexthop(), dtn::BundleDaemon::handle_registration_added(), dtn::ProphetBundleOffer::ProphetBundleOffer(), dtn::ProphetBundleQueue::ProphetBundleQueue(), and dtn::BundleReportEvent::serialize().

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.

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

Definition at line 453 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 468 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 243 of file BundleList.h.

References lock_.

Referenced by dtn::FragmentManager::check_completed(), dtn::TableBasedRouter::check_next_hop(), dtn::BundleCommand::exec(), dtn::ProphetBundleList::find(), dtn::BundleDaemon::find_duplicate(), dtn::ProphetEncounter::fwd_to_nexthop(), dtn::BundleDaemon::handle_registration_added(), dtn::ProphetBundleOffer::ProphetBundleOffer(), dtn::ProphetBundleQueue::ProphetBundleQueue(), and dtn::BundleReportEvent::serialize().

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

Return the identifier name of this list.

Definition at line 248 of file BundleList.h.

References name_.

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

Set the name (useful for classes that are unserialized).

Definition at line 38 of file BundleList.cc.

References oasys::Logger::logpathf(), and name_.

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

Helper routine to add a bundle at the indicated position.

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

Definition at line 87 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 199 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 273 of file BundleList.h.

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

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

Definition at line 274 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 275 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 276 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 Sat Sep 8 08:36:21 2007 for DTN Reference Implementation by  doxygen 1.5.3