| STAPL API Reference |
Modules Classes |
|
The primary storage class for dependence and data flow values in the PARAGRAPH. One instance of this class or the base class edge_entry_base exists for each producer task, both on the location where it executes as well as on all locations with active consumers. More...
Public Member Functions | |
| edge_entry & | operator= (edge_entry const &)=delete |
| edge_entry (edge_entry const &)=delete | |
| edge_entry (std::size_t tid, bool b_persistent) | |
| edge_entry (edge_entry_base &&other) | |
| Constructor called to upgrade a edge_entry_base element of the edge_container to edge value typed instance of this class template. More... | |
| ~edge_entry () final | |
Remove all notifications if not part of persistent PARAGRAPH and remove version entries stored m_versions. | |
| void | cleanup_notifications (void) final |
| Clear all local and remote notifications stored in the entry. More... | |
| bool | has_unnotified_local_consumer () const |
| Return true if there are any local notifications in this entry that have not yet been flushed by a data flow trigger. | |
| template<typename Filter > | |
| tuple< df_add_status, unsigned int, edge_version_storage< typename df_stored_type< typename boost::result_of< Filter(stored_value_t)>::type >::type > & > | add_local_notifier (edge_container &ct, boost::function< void(executor_base &, typename df_stored_type< typename boost::result_of< Filter(typename df_stored_type< T >::type const &) >::type >::type const &) > const ¬ifier, bool b_inc_local_usr_cnt, Filter const &filter) |
Receive a local consumption request with associated notifier and filter. Integrate it into edge_entry's local dependence representation and signal caller (edge_container::setup_flow) if any remote notification is required. More... | |
| tuple< df_add_status, unsigned int, edge_version_storage< stored_value_t > & > | add_local_notifier (edge_container &ct, boost::function< void(executor_base &, stored_value_t const &) > const ¬ifier, bool b_inc_local_usr_cnt, detail::df_identity< stored_value_t > const &) |
| Signature of function for identity / full value consumption. | |
| template<typename Notifier > | |
| void | add_remote_notifier (edge_container &ct, Notifier const ¬ifier, const size_t loc, const bool b_upgrade) |
| Add a notifier to transmit a producer value (full or filtered) to a remote consumer location and trigger data flow of local consumer edges there. More... | |
| void | add_remote_signal_notifier (edge_container &ct, size_t loc) final |
| Add a signal notifier to notify a remote consumer location when a producer task finishes execution. More... | |
| void | set_shared_value (immutable_shared< stored_value_t > const &wrapper, edge_container &ct, unsigned int version_id, bool b_caller_is_set_element=false, bool b_caller_is_migration=false) |
| Used to trigger data flow in this entry for edges that can be serviced with the version of the value that has been passed via immutable sharing. | |
| template<typename Filter , typename ValueParam > | |
| void | set_value_impl (ValueParam &&val, edge_container &ct, unsigned int version_id, bool b_caller_is_set_element, bool b_migration_enabled, bool b_expect_exist, std::true_type) |
| Implementation helper function for set_value to handle full version set value calls. | |
| template<typename Filter , typename ValueParam > | |
| void | set_value_impl (ValueParam &&val, edge_container &ct, unsigned int version_id, bool b_caller_is_set_element, bool b_migration_enabled, bool b_expect_exist, std::false_type) |
| Implementation helper function for set_value to handle filtered versions set value calls. | |
| template<typename Filter > | |
| void | set_value (immutable_shared< stored_value_t > &&wrapper, edge_container &ct, unsigned int version_id, bool b_caller_is_set_element=false, bool b_caller_is_migration=false) |
| template<typename Filter , typename ValueParam > | |
| void | set_value (ValueParam &&val, edge_container &ct, unsigned int version_id, bool b_caller_is_set_element=false, bool b_caller_is_migration=false) |
| Used to trigger data flow in this entry for edges that can be serviced with the version of the value that has been passed. More... | |
| void | set_value (edge_container &ct) final |
| Used to trigger data flow in this entry for edges that are void. More... | |
| bool | persistent_evictable (void) const |
| The general evictability test for the edge_entry. Detects whether this entry is no longer needed on the location and can be removed. More... | |
| bool | evictable (void) const |
| Check whether this entry is no longer needed on the location and can be removed. More... | |
| size_t | migrate (remote_notifier_list_t &other, int &ct_unknown_consumer_cnt) |
| Extract all state necessary to migrate the producer state from this entry and move it to new execution location. More... | |
| void | reset_values (void) final |
| Reset data flow triggers prior to a persistent PARAGRAPH reinvocation. More... | |
| bool | full_value_set (void) const final |
| Return true if the full value of the producer task is currently available (i.e., data flow triggered) in this entry. | |
| bool | stealable (void) const |
| Called in Task::operator() (via lazy_edge_reference) by a consumer identity operation to avoid needless copy if it can have a version stored in edge_version_storage. | |
| bool | out_edge_stealable (void) |
Called when attempting to use object managed by edge entry as outgoing edge of paragraph. m_local_user_cnt should be zero as result notifications do not increment this variable. | |
| virtual bool | is_basic_edge_entry (void) const |
| bool | is_signal_only (void) const |
| bool | is_persistent (void) const |
| std::size_t | tid (void) const |
| void | set_as_producer (size_t consumer_cnt) |
| Inform this edge entry that the producer task has been initialized on this location. More... | |
| void | delayed_set_num_consumers (size_t consumer_cnt) |
Set the number of successors after delay_spec was passed to set_as_producer. More... | |
| void | decrement_unknown_consumers (void) |
| Reduce the unregistered consumer count. More... | |
| void | increment_local_consumers (void) |
| Increase reference count of local proxies in use by consumer tasks and backed by a version in this edge entry. More... | |
| void | decrement_local_consumers (void) |
| Decrease reference count of local proxies in use by consumer tasks and backed by a version in this edge entry. More... | |
| bool | local_producer_initialized () const |
| Check if the producer task for edge_entry is registered on this location. More... | |
| bool | has_single_consumer (void) const noexcept |
| bool | signal_set () const |
| Redirect check signal flow request to the signal version notifier list. | |
| void | set_signal (executor_base *executor_ptr, const bool b_migration_enabled) |
| Set data flow for signal consumers by notifying the signal version notifier list. More... | |
| df_add_status | compute_request_status (const edge_request_type req, const bool b_flow, const bool b_partial_added=false) |
| Called when adding a local notification to determine whether a a consumption request is covered by previous requests or whether a new remote notifier needs to be generated and sent to the producer location. More... | |
| df_add_status | add_signal_notifier (executor_base &executor, signal_notifier_t notifier) |
| Add a signal notifier for a local task. Return the request level status information by calling compute_request_status. More... | |
Public Types | |
| typedef remote_edge_version_entry_t::entry_t | remote_notifier_entry_t |
| Remote version entry type reflected publicly for migration support. | |
| typedef remote_edge_version_entry_t::notifier_list_t | remote_notifier_list_t |
| Remote version list type reflected publicly for migration support. | |
Protected Member Functions | |
| bool | empty_signal_notifications (void) const |
Return true if the the edge_entry contains any signal notifications. | |
Protected Attributes | |
| const std::size_t | m_tid |
| Task identifier of the produce task this entry refers to. | |
| edge_request_type | m_request_state |
| The current level of consumption on location where this entry exists. | |
| size_t | m_unknown_consumer_cnt |
Count of consumers which are still unaccounted for. Only initialized on producer location, where the edge_entry will be kept in edge_container at least until all consumers have registered, decrementing this field to 0. Value of defer_spec, denotes location is set as producer location, but successor count will be set separately. More... | |
| bool | m_single_consumer |
true if there is only one consumer. | |
| size_t | m_seen_consumers |
| Tracks the number of consumers that have registered at producer location when m_unknown_consumer_cnt is set to defer_spec. | |
| size_t | m_local_user_cnt |
| track of consumer reference to version contained in this entry. Used to help manage the lifetime of the object. | |
| const bool | m_b_persistent |
| Tracks whether corresponding PARAGRAPH is persistent. | |
| const bool | m_b_signal_only |
Is the actual object instantiated edge_entry_base or edge_entry<T>. Used to detect if we need to upgrade the entry based to edge_entry object. More... | |
| bool | m_b_consumers_before_producer |
| Tracks whether consumer tasks at this location registered before the producer was registered. If so, their remote notifiers may arrive out of order. In debug mode, we need to track this for assertion. More... | |
Friends | |
| bool | operator== (edge_entry const &lhs, edge_entry const &rhs) |
Freestanding version of operator defined for the edge_entry in terms of the entries' task identifiers. Used by the Boost.Intrusive unordered_set in which all entries are stored by the edge_container. | |
| std::ostream & | operator<< (std::ostream &os, edge_entry< T > const &entry) |
| Define insertion operator on ostream. Provides useful debugging information. More... | |
The primary storage class for dependence and data flow values in the PARAGRAPH. One instance of this class or the base class edge_entry_base exists for each producer task, both on the location where it executes as well as on all locations with active consumers.
| The | return type of the producer task's workfunction. |
Each entry maintains a collection of notifier lists called versions. A version may be held in the entry object frame (for now remote and signal versions are held this way) or in a versions list held as data member (currently the case for filtered and full versions). This is strictly an implementation detail that likely warrants further investigation.
The only component interacting with the edge_entry directly is the edge_container which maintains all entries for a given location in a container. The edge_container redirects most requests from outside callers to the appropriate entry methods.
|
explicit |
Constructor called to upgrade a edge_entry_base element of the edge_container to edge value typed instance of this class template.
This is effectively a move constructor and that calls the similarly defined move constructor of edge_entry_base.
|
finalvirtual |
Clear all local and remote notifications stored in the entry.
Either called in the destructor or as part of the delayed edge_container destruction used when persistency support is enabled.
Reimplemented from stapl::detail::edge_entry_base.
| tuple<df_add_status, unsigned int, edge_version_storage< typename df_stored_type< typename boost::result_of< Filter(stored_value_t)>::type>::type>&> stapl::detail::edge_entry< T >::add_local_notifier | ( | edge_container & | ct, |
| boost::function< void(executor_base &, typename df_stored_type< typename boost::result_of< Filter(typename df_stored_type< T >::type const &) >::type >::type const &) > const & | notifier, | ||
| bool | b_inc_local_usr_cnt, | ||
| Filter const & | filter | ||
| ) |
Receive a local consumption request with associated notifier and filter. Integrate it into edge_entry's local dependence representation and signal caller (edge_container::setup_flow) if any remote notification is required.
| ct | the edge_container holding this edge_entry. |
| notifier | The notifier to invoke when the requested data flow is complete and available for consumption. |
| filter | The filtering function to be applied on the producer task's value prior to passing it successor. |
| b_inc_local_usr_cnt | Denotes whether this is a consumer that will rely on the entry's copy of the flowed value. Guides internal reference counting. |
| void stapl::detail::edge_entry< T >::add_remote_notifier | ( | edge_container & | ct, |
| Notifier const & | notifier, | ||
| const size_t | loc, | ||
| const bool | b_upgrade | ||
| ) |
Add a notifier to transmit a producer value (full or filtered) to a remote consumer location and trigger data flow of local consumer edges there.
| ct | The edge container this entry is held by. |
| notifier | The notifier to called when the producer task finishes execution (encapsulate any filter function). |
| loc | The location this notifier originated from. |
| b_upgrade | Denotes whether this request upgrades a previous remote notification from location loc to higher request level (i.e., FILTERED –> FULL). |
Currently only called on the producer location.
|
finalvirtual |
Add a signal notifier to notify a remote consumer location when a producer task finishes execution.
| ct | The edge container this entry is held by. |
| loc | The location this notifier originated from. |
Reimplemented from stapl::detail::edge_entry_base.
| void stapl::detail::edge_entry< T >::set_value | ( | ValueParam && | val, |
| edge_container & | ct, | ||
| unsigned int | version_id, | ||
| bool | b_caller_is_set_element = false, |
||
| bool | b_caller_is_migration = false |
||
| ) |
Used to trigger data flow in this entry for edges that can be serviced with the version of the value that has been passed.
| val | The edge value that has been flowed. |
| ct | The edge container this entry is held by. |
| version_id | The version identifier for val. Zero if the full producer. Otherwise a filtered version with the identifier previously assigned in add_local_notifier. |
| b_caller_is_set_element | Denotes whether the caller of this method is set_element (i.e., the original data flow directly from the producer task). |
| b_caller_is_migration | Denotes this is called when moving a predecessor value for a successor migrated task. Guards assertions checking previous existence of value (to verify protocol correctness). |
|
finalvirtual |
Used to trigger data flow in this entry for edges that are void.
| ct | The edge_container holding this entry. |
Redirect to general set_value with default constructed value (this type may be unknown in the calling context, as this is a virtual function that can be called through edge_entry_base.
Reimplemented from stapl::detail::edge_entry_base.
| bool stapl::detail::edge_entry< T >::persistent_evictable | ( | void | ) | const |
The general evictability test for the edge_entry. Detects whether this entry is no longer needed on the location and can be removed.
Verifies all consumers have been registered and notified (if this is the producer location) and that no local consumers are still using any version maintained by the entry.
| bool stapl::detail::edge_entry< T >::evictable | ( | void | ) | const |
Check whether this entry is no longer needed on the location and can be removed.
Guarded to return false if the PARAGRAPH is persistent. Eviction attempts in the edge container are disabled, allowing entry to remain until the destructor of the edge_container (as part of overall PARAGRAPH destruction).
| size_t stapl::detail::edge_entry< T >::migrate | ( | remote_notifier_list_t & | other, |
| int & | ct_unknown_consumer_cnt | ||
| ) |
Extract all state necessary to migrate the producer state from this entry and move it to new execution location.
| other | A reference to an empty notifier list. Move all remote notifiers into this. edge_container::migrate_entry will forward these notifiers there after invoking directory::migrate. |
| ct_unknown_consumer_cnt | A reference to the edge container's global unknown consumer count. Decrement with entry's current unknown count, as these are now another location's responsibility to track. |
|
finalvirtual |
Reset data flow triggers prior to a persistent PARAGRAPH reinvocation.
Reset the remote version list and all versions stored in the versions list. Also invoke edge_entry_base::reset_values to reset the signal version list.
Reimplemented from stapl::detail::edge_entry_base.
|
inherited |
Inform this edge entry that the producer task has been initialized on this location.
| consumer_cnt | The number of consumers as specified by the corresponding add_task call. Possible value is defer_spec, denoting that this count will be specified later. |
|
inherited |
Set the number of successors after delay_spec was passed to set_as_producer.
| consumer_cnt | The out-degree of the producer task in the PARAGRAPH. |
|
inherited |
Reduce the unregistered consumer count.
Called when previous consumption on a consumer location covers a request, meaning no additional notifications are required. A simple decrement of out-degree counter is sufficient.
|
inherited |
Increase reference count of local proxies in use by consumer tasks and backed by a version in this edge entry.
|
inherited |
Decrease reference count of local proxies in use by consumer tasks and backed by a version in this edge entry.
|
inherited |
Check if the producer task for edge_entry is registered on this location.
Sufficient to check if m_unknown_consumer_cnt has been initialized.
|
inherited |
Set data flow for signal consumers by notifying the signal version notifier list.
| executor_ptr | The executor associated with the given PARAGRAPH. |
| b_migration_enabled | Denotes whether the PARAGRAPH has task migration support enabled. |
|
inherited |
Called when adding a local notification to determine whether a a consumption request is covered by previous requests or whether a new remote notifier needs to be generated and sent to the producer location.
| req | The type of request that has just been added. |
| b_flow | Whether data flow has already been triggered on this consumer location for req. |
| b_partial_added | If req is partial, denotes if this request added a new version (i.e., filter) on this location for the producer task value. |
|
inherited |
Add a signal notifier for a local task. Return the request level status information by calling compute_request_status.
| executor | The executor associated with the PARAGRAPH. Passed to notifier if it is immediately called (i.e., the signal flow has already been set. |
| notifier | The signal notifier for the successor task. |
|
friend |
Define insertion operator on ostream. Provides useful debugging information.
| os | The output stream to insert into. |
| entry | The edge entry to insert information about into the stream. |
|
protectedinherited |
Count of consumers which are still unaccounted for. Only initialized on producer location, where the edge_entry will be kept in edge_container at least until all consumers have registered, decrementing this field to 0. Value of defer_spec, denotes location is set as producer location, but successor count will be set separately.
|
protectedinherited |
Is the actual object instantiated edge_entry_base or edge_entry<T>. Used to detect if we need to upgrade the entry based to edge_entry object.
|
protectedinherited |
Tracks whether consumer tasks at this location registered before the producer was registered. If so, their remote notifiers may arrive out of order. In debug mode, we need to track this for assertion.
1.8.13