#include <safe_list.h>
Inheritance diagram for nodes::safe_list:
Public Types | |
| typedef common::list_positions | iterator_positions |
Public Member Functions | |
| safe_list () | |
| creates a thread safe list that will clean its contents when destroyed. | |
| ~safe_list () | |
| IMPLEMENT_CLASS_NAME ("safe_list") | |
| safe_list_read_iterator * | open_reader (iterator_positions where=HEAD) |
| creates a new read_iterator on this list. | |
| safe_list_write_iterator * | open_writer (iterator_positions where=HEAD) |
| creates a new write_iterator on this list. | |
| void | close_reader (safe_list_read_iterator *&to_close) |
| shuts down the read iterator. | |
| void | close_writer (safe_list_write_iterator *&to_close) |
| shuts down the write iterator. | |
| bool | empty (safe_list_read_iterator &hook) |
| returns true if the list is empty. | |
| bool | empty (safe_list_write_iterator &hook) |
| returns true if the list is empty. | |
| int | elements (safe_list_read_iterator &hook) |
| returns the number of elements in the list. | |
| int | elements (safe_list_write_iterator &hook) |
| returns the number of elements in the list. | |
| void | zap (safe_list_write_iterator &writer) |
| destroys the current safe_node using the lock from the "writer". | |
| void | insert (safe_list_write_iterator &writer, safe_node *to_insert) |
| inserts a node "to_insert" at the "writer" position. | |
| safe_node * | remove (safe_list_write_iterator &writer) |
| extracts the current safe_node at the position in the "writer". | |
Static Public Attributes | |
| static const iterator_positions | HEAD |
| the list beginning. | |
| static const iterator_positions | TAIL |
| the list end. | |
Friends | |
| class | safe_list_read_iterator |
| class | safe_list_write_iterator |
The list is protected from race conditions by categorizing methods on the list into read and write operations. Operations that modify the list contents or structure are considered write operations, while others that only examine the contents of the list without changing its structure are read operations. Only one writer may lock the list or list elements at a time, but many readers may share a read lock. These restrictions are implemented by providing two types of iterators, one for reading and another writing. The only way to access the safe_list at all is through these iterators. The iterators ensure that the access pattern is controlled as described above. To use the safe_list, your structure to be stored in the list must be derived from the safe_node type, which is defined separately.
NOTE: reading the documentation for the list class (nodes/list.h) is highly beneficial for understanding usage of this object. The safe_list is essentially the same interface, but is aimed at thread safety.
Definition at line 53 of file safe_list.h.
Definition at line 65 of file safe_list.h.
| nodes::safe_list::safe_list | ( | ) |
creates a thread safe list that will clean its contents when destroyed.
Definition at line 187 of file safe_list.cpp.
| nodes::safe_list::~safe_list | ( | ) |
| nodes::safe_list::IMPLEMENT_CLASS_NAME | ( | "safe_list" | ) |
| safe_list_read_iterator * nodes::safe_list::open_reader | ( | iterator_positions | where = HEAD |
) |
creates a new read_iterator on this list.
note that any iterators that you open must be closed before the safe_list is destroyed. they also should be closed as soon as possible to avoid contention on the list.
Definition at line 210 of file safe_list.cpp.
References reader_writer_lock::begin_read(), and safe_list_read_iterator.
| safe_list_write_iterator * nodes::safe_list::open_writer | ( | iterator_positions | where = HEAD |
) |
creates a new write_iterator on this list.
Definition at line 216 of file safe_list.cpp.
References reader_writer_lock::begin_write(), and safe_list_write_iterator.
Referenced by scheduler::add(), scheduler::filter_missing_actors(), scheduler::find(), scheduler::open_iterator(), scheduler::remove_by_actor(), scheduler::remove_by_id(), and scheduler::~scheduler().
| void nodes::safe_list::close_reader | ( | safe_list_read_iterator *& | to_close | ) |
shuts down the read iterator.
Definition at line 222 of file safe_list.cpp.
References reader_writer_lock::end_read(), and WHACK().
| void nodes::safe_list::close_writer | ( | safe_list_write_iterator *& | to_close | ) |
shuts down the write iterator.
Definition at line 228 of file safe_list.cpp.
References reader_writer_lock::end_write(), and WHACK().
Referenced by scheduler::add(), scheduler::close_iterator(), scheduler::filter_missing_actors(), scheduler::find(), scheduler::remove_by_actor(), scheduler::remove_by_id(), and scheduler::~scheduler().
| bool nodes::safe_list::empty | ( | safe_list_read_iterator & | hook | ) |
returns true if the list is empty.
note that an iterator is necessary to ensure the list semantics are not violated. it is not modified.
Referenced by scheduler::~scheduler().
| bool nodes::safe_list::empty | ( | safe_list_write_iterator & | hook | ) |
returns true if the list is empty.
| int nodes::safe_list::elements | ( | safe_list_read_iterator & | hook | ) |
returns the number of elements in the list.
this is a fairly costly operation. note that an iterator is necessary to ensure the list semantics are not violated. it is not modified.
| int nodes::safe_list::elements | ( | safe_list_write_iterator & | hook | ) |
returns the number of elements in the list.
| void nodes::safe_list::zap | ( | safe_list_write_iterator & | writer | ) |
destroys the current safe_node using the lock from the "writer".
the current position in the iterator is set to the safe_node that used to reside after the unfortunate deceased safe_node (or to the new end of the list if that was the last safe_node).
Definition at line 248 of file safe_list.cpp.
References CAST_WRITER, and nodes::list::zap().
Referenced by scheduler::filter_missing_actors(), scheduler::remove_by_actor(), scheduler::remove_by_id(), scheduler::zap(), and scheduler::~scheduler().
| void nodes::safe_list::insert | ( | safe_list_write_iterator & | writer, | |
| safe_node * | to_insert | |||
| ) |
inserts a node "to_insert" at the "writer" position.
adds the safe_node "to_insert" into the list at the current position using the lock from the "writer". the safe_node that used to be at the current position in the iterator will now be after this safe_node and "writer" will now be pointing at the node "to_insert".
Definition at line 254 of file safe_list.cpp.
References CAST_WRITER, and nodes::list::insert().
Referenced by scheduler::add().
| safe_node * nodes::safe_list::remove | ( | safe_list_write_iterator & | writer | ) |
extracts the current safe_node at the position in the "writer".
the safe_list relinquishes responsibility for the safe_node after it is taken out of the list. NIL is returned if the list is empty.
Definition at line 237 of file safe_list.cpp.
References CAST_WRITER, NIL, and nodes::list::remove().
friend class safe_list_read_iterator [friend] |
friend class safe_list_write_iterator [friend] |
const safe_list::iterator_positions nodes::safe_list::HEAD [static] |
the list beginning.
Definition at line 66 of file safe_list.h.
Referenced by nodes::safe_list_read_iterator::safe_list_read_iterator(), and nodes::safe_list_write_iterator::safe_list_write_iterator().
const safe_list::iterator_positions nodes::safe_list::TAIL [static] |
the list end.
Definition at line 67 of file safe_list.h.
Referenced by nodes::object_catalog::add(), and nodes::object_catalog::find_tail().
1.5.1