dtn::BundleList Class Reference

#include <BundleList.h>

Inheritance diagram for dtn::BundleList:

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 67 of file bundling/BundleList.h.


Public Types

enum  sort_order_t { SORT_PRIORITY = 0x1, SORT_FRAG_OFFSET }
 Type codes for sorted insertion. More...
typedef List::iterator iterator
 Type for an iterator, which just wraps an stl iterator.

Public Member Functions

 BundleList (const std::string &name, oasys::SpinLock *lock=NULL)
 Constructor.
virtual ~BundleList ()
 Destructor -- clears the list.
BundleRef front () const
 Peek at the first bundle on the list.
BundleRef back () const
 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_front (const BundleRef &bundle)
 Add a new bundle to the front of the list.
void push_back (Bundle *bundle)
 Add a new bundle to the back of the list.
void push_back (const BundleRef &bundle)
 Add a new bundle to the back 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 erase (const BundleRef &bundle, bool used_notifier=false)
void erase (iterator &iter, bool used_notifier=false)
 Remove the bundle at the given list position.
bool contains (Bundle *bundle) const
 Search the list for the given bundle.
bool contains (const BundleRef &bundle) const
 Search the list for the given bundle.
BundleRef find (u_int32_t bundleid) const
 Search the list for a bundle with the given id.
BundleRef find (const EndpointID &source_eid, const BundleTimestamp &creation_ts) const
 Search the list for a bundle with the given source eid and timestamp.
BundleRef find (GbofId &gbof_id) const
 Search the list for a bundle with the given GBOF ID.
BundleRef find (const GbofId &gbof_id, const BundleTimestamp &extended_id) const
 Search the list for a bundle with the given GBOF ID and extended (local) ID.
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.
bool empty () const
 Return whether or not the list is empty.
iterator begin () const
 Iterator used to iterate through the list.
iterator end () const
 Iterator used to mark the end of the list.
oasys::SpinLock * lock () 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 Attributes

oasys::SpinLock * lock_
 lock for notifier
bool own_lock_
 bit to define lock ownership
oasys::Notifier * notifier_
 notifier for blocking list

Private Types

typedef std::list< Bundle * > List
 Type for the list itself (private since it's irrelevant to the outside).

Private 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.

Private Attributes

std::string name_
 name of the list
List list_
 underlying list data structure

Member Typedef Documentation

typedef std::list<Bundle*> dtn::BundleList::List [private]

Type for the list itself (private since it's irrelevant to the outside).

Definition at line 73 of file bundling/BundleList.h.

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

Type for an iterator, which just wraps an stl iterator.

We don't ever use the stl const_iterator type since list mutations are protected via this class' methods.

Definition at line 81 of file bundling/BundleList.h.


Member Enumeration Documentation

Type codes for sorted insertion.

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

Definition at line 136 of file bundling/BundleList.h.


Constructor & Destructor Documentation

dtn::BundleList::BundleList ( const std::string &  name,
oasys::SpinLock *  lock = NULL 
)

Constructor.

Definition at line 33 of file BundleList.cc.

References lock_, and own_lock_.

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

Destructor -- clears the list.

Definition at line 55 of file BundleList.cc.

References clear(), lock_, and own_lock_.


Member Function Documentation

BundleRef dtn::BundleList::front (  )  const

Peek at the first bundle on the list.

Returns:
the bundle or NULL if the list is empty

Definition at line 66 of file BundleList.cc.

References list_, and lock_.

Referenced by dtn::ProphetBundleList::clear().

BundleRef dtn::BundleList::back (  )  const

Peek at the last bundle on the list.

Returns:
the bundle or NULL if the list is empty

Definition at line 80 of file BundleList.cc.

References list_, and lock_.

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

Add a new bundle to the front of the list.

Definition at line 121 of file BundleList.cc.

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

Referenced by push_front().

void dtn::BundleList::push_front ( const BundleRef bundle  )  [inline]

Add a new bundle to the front of the list.

Definition at line 115 of file bundling/BundleList.h.

References push_front().

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

void dtn::BundleList::push_back ( const BundleRef bundle  )  [inline]

Add a new bundle to the back of the list.

Definition at line 128 of file bundling/BundleList.h.

References push_back().

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

References add_bundle(), dtn::Bundle::frag_offset(), list_, dtn::Bundle::lock(), lock_, SORT_FRAG_OFFSET, and SORT_PRIORITY.

Referenced by dtn::FragmentState::add_fragment().

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(), empty(), dtn::Bundle::lock(), lock_, 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.

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

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

Referenced by clear(), dtn::TclRegistration::get_bundle_data(), dtn::BundleDaemon::handle_reassembly_completed(), dtn::APIClient::handle_recv(), dtn::APIClient::handle_session_update(), 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 256 of file BundleList.cc.

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

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

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

bool dtn::BundleList::erase ( const BundleRef bundle,
bool  used_notifier = false 
) [inline]

Definition at line 188 of file bundling/BundleList.h.

References erase().

void dtn::BundleList::erase ( iterator iter,
bool  used_notifier = false 
)

Remove the bundle at the given list position.

Definition at line 313 of file BundleList.cc.

References ASSERT, del_bundle(), dtn::Bundle::del_ref(), dtn::Bundle::lock(), lock_, and name_.

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

bool dtn::BundleList::contains ( const BundleRef bundle  )  const [inline]

Search the list for the given bundle.

Returns:
true if found, false if not

Definition at line 209 of file bundling/BundleList.h.

References contains().

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

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

References begin(), end(), 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 
) const

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

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

BundleRef dtn::BundleList::find ( GbofId gbof_id  )  const

Search the list for a bundle with the given GBOF ID.

Returns:
the bundle or NULL if not found.

Definition at line 387 of file BundleList.cc.

References begin(), end(), dtn::GbofId::equals(), and lock_.

BundleRef dtn::BundleList::find ( const GbofId gbof_id,
const BundleTimestamp extended_id 
) const

Search the list for a bundle with the given GBOF ID and extended (local) ID.

Returns:
the bundle or NULL if not found.

Definition at line 409 of file BundleList.cc.

References begin(), end(), dtn::GbofId::equals(), and lock_.

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

Move all bundles from this list to another.

Definition at line 432 of file BundleList.cc.

References list_, lock_, pop_front(), and push_back().

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

void dtn::BundleList::clear (  ) 

Clear out the list.

Definition at line 446 of file BundleList.cc.

References list_, lock_, and pop_front().

Referenced by ~BundleList().

size_t dtn::BundleList::size (  )  const

bool dtn::BundleList::empty (  )  const

Return whether or not the list is empty.

Definition at line 467 of file BundleList.cc.

References list_, and lock_.

Referenced by dtn::FragmentManager::delete_obsoleted_fragments(), insert_random(), dtn::BlockingBundleList::pop_blocking(), pop_front(), and dtn::APIClient::wait_for_notify().

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

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

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

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

Return the identifier name of this list.

Definition at line 290 of file bundling/BundleList.h.

References name_.

Referenced by dtn::BlockingBundleList::pop_blocking().

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

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

Definition at line 48 of file BundleList.cc.

References name_.

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

Helper routine to add a bundle at the indicated position.

Definition at line 94 of file BundleList.cc.

References dtn::Bundle::add_ref(), ASSERT, dtn::Bundle::bundleid(), dtn::Bundle::is_queued_on(), list_, dtn::Bundle::lock(), lock_, dtn::Bundle::mappings(), name_, and notifier_.

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

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

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

References ASSERT, dtn::Bundle::bundleid(), dtn::BundleMappings::find(), list_, dtn::Bundle::lock(), lock_, dtn::Bundle::mappings(), name_, and notifier_.

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


Member Data Documentation

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

name of the list

Definition at line 315 of file bundling/BundleList.h.

Referenced by add_bundle(), del_bundle(), erase(), name(), pop_back(), pop_front(), and set_name().

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

bit to define lock ownership

Definition at line 320 of file bundling/BundleList.h.

Referenced by BundleList(), and ~BundleList().

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


The documentation for this class was generated from the following files:

Generated on Mon Jul 21 14:12:20 2008 for DTN Reference Implementation by  doxygen 1.5.6