Public Types | Public Member Functions | Static Public Member Functions

graphlab::iengine< Graph > Class Template Reference

The abstract interface of a GraphLab engine. The graphlab engine interface describes the core functionality provided by all graphlab engines. The engine is templatized over the type of graph. More...

#include <iengine.hpp>

Inheritance diagram for graphlab::iengine< Graph >:
graphlab::distributed_chromatic_engine< Graph > graphlab::distributed_locking_engine< Graph, Scheduler >

List of all members.

Public Types

typedef Graph graph_type
 The type of graph that the engine operates on.
typedef update_task< Graph > update_task_type
 The type of update task.
typedef
update_task_type::update_function_type 
update_function_type
 The type of update function.
typedef ischeduler< Graph > ischeduler_type
 The type of scheduler.
typedef imonitor< Graph > imonitor_type
 The type of monitor.
typedef iscope< Graph > iscope_type
 The type of scope.
typedef void(* sync_function_type )(iscope_type &scope, any &accumulator)
typedef void(* merge_function_type )(any &merge_dest, const any &merge_src)
typedef bool(* termination_function_type )()

Public Member Functions

virtual ~iengine ()
 Virtual destructor required for inheritance.
virtual size_t get_ncpus () const =0
 get the number of cpus
virtual void set_default_scope (scope_range::scope_range_enum default_scope_range)=0
 Set the default scope range.
virtual void start ()=0
 Start the engine execution.
virtual void stop ()=0
 Force engine to terminate immediately.
virtual exec_status last_exec_status () const =0
 Describe the reason for termination.
virtual size_t last_update_count () const =0
 Get the number of updates executed by the engine.
virtual void register_monitor (imonitor_type *listener)=0
 Register a monitor with an engine.
virtual void add_task (update_task_type task, double priority)=0
 Adds an update task with a particular priority. This function is forwarded to the scheduler.
virtual void add_vtask (vertex_id_t vid, update_function_type fun, double priority=1.0)
 Add an update function to a particular vertex.
virtual void add_tasks (const std::vector< vertex_id_t > &vertices, update_function_type func, double priority)=0
 Creates a collection of tasks on all the vertices in 'vertices', and all with the same update function and priority This function is forwarded to the scheduler.
virtual void add_task_to_all (update_function_type func, double priority)=0
 Creates a collection of tasks on all the vertices in the graph, with the same update function and priority This function is forwarded to the scheduler.
virtual void add_terminator (termination_function_type term)=0
 associate a termination function with this engine.
virtual void clear_terminators ()=0
 remove all associated termination functions
virtual void set_sched_yield (bool value)
virtual void set_cpu_affinities (bool value)
virtual void set_timeout (size_t timeout_secs)=0
 The timeout is the total ammount of time in seconds that the engine may run before exeuction is automatically terminated.
virtual void set_task_budget (size_t max_tasks)=0
 set a limit on the number of tasks that may be executed.
virtual void set_scheduler_options (const scheduler_options &opts)=0
 Update the scheduler options.
virtual void set_engine_options (const scheduler_options &opts)=0
 Update the engine options.
virtual void set_sync (glshared_base &shared, sync_function_type sync, glshared_base::apply_function_type apply, const any &zero, size_t sync_interval=0, merge_function_type merge=NULL, vertex_id_t rangelow=0, vertex_id_t rangehigh=-1)=0
 Registers a sync with the engine.
virtual void sync_now (glshared_base &shared)=0
virtual metrics get_metrics ()
virtual void reset_metrics ()
virtual void report_metrics (imetrics_reporter &reporter)

Static Public Member Functions

static std::string exec_status_as_string (exec_status es)

Detailed Description

template<typename Graph>
class graphlab::iengine< Graph >

The abstract interface of a GraphLab engine. The graphlab engine interface describes the core functionality provided by all graphlab engines. The engine is templatized over the type of graph.

The GraphLab engines are a core element of the GraphLab framework. The engines are responsible for applying a the update tasks and sync operations to a graph and shared data using the scheduler to determine the update schedule. This class provides a generic interface to interact with engines written to execute on different platforms.

While users are free to directly instantiate the engine of their choice we highly recommend the use of the core data structure to manage the creation of engines. Alternatively, users can use the graphlab::engine_factory::new_engine static functions to create engines directly from configuration strings.

Definition at line 92 of file iengine.hpp.


Member Typedef Documentation

template<typename Graph>
typedef bool(* graphlab::iengine< Graph >::termination_function_type)()

The termination function is a function that reads the shared data and returns true if the engine should terminate execution. The termination function is called at fixed millisecond intervals and therefore the engine may continue to execute even after a termination function evaluates to true. Because termination functions are executed frequently and cannot directly contribut to the computation, they should return quickly.

Reimplemented in graphlab::distributed_chromatic_engine< Graph >, graphlab::distributed_locking_engine< Graph, Scheduler >, graphlab::asynchronous_engine< Graph, Scheduler, ScopeFactory >, graphlab::distributed_chromatic_engine< distributed_graph >, graphlab::distributed_locking_engine< distributed_graph, Scheduler >, and graphlab::asynchronous_engine< graph, Scheduler, ScopeFactory >.

Definition at line 131 of file iengine.hpp.


Member Function Documentation

template<typename Graph>
virtual void graphlab::iengine< Graph >::add_terminator ( termination_function_type  term  )  [pure virtual]

associate a termination function with this engine.

An engine can typically have many termination functions associated with it. A termination function is a function which takes a constant reference to the shared data and returns a boolean which is true if the engine should terminate execution.

A termination function has the following type:

 bool term_fun(const ishared_data_type* shared_data)
template<typename Graph>
virtual size_t graphlab::iengine< Graph >::last_update_count (  )  const [pure virtual]
template<typename Graph>
virtual void graphlab::iengine< Graph >::register_monitor ( imonitor_type listener  )  [pure virtual]
template<typename Graph>
virtual void graphlab::iengine< Graph >::report_metrics ( imetrics_reporter &  reporter  )  [inline, virtual]

Writes out the metrics information logged by the engine and all subordinate classes.

Engine writers should note that for dump_metrics() to work, the engine only has to implement get_metrics() and reset_metrics(). Default behavior is to report the metrics returned by get_metrics() and call reset_metrics(). This behavior may be overridden by implementing this function.

See also:
get_metrics reset_metrics

Reimplemented in graphlab::asynchronous_engine< Graph, Scheduler, ScopeFactory >, and graphlab::asynchronous_engine< graph, Scheduler, ScopeFactory >.

Definition at line 382 of file iengine.hpp.

template<typename Graph>
virtual void graphlab::iengine< Graph >::set_default_scope ( scope_range::scope_range_enum  default_scope_range  )  [pure virtual]
template<typename Graph>
virtual void graphlab::iengine< Graph >::set_sched_yield ( bool  value  )  [inline, virtual]
template<typename Graph>
virtual void graphlab::iengine< Graph >::set_sync ( glshared_base shared,
sync_function_type  sync,
glshared_base::apply_function_type  apply,
const any zero,
size_t  sync_interval = 0,
merge_function_type  merge = NULL,
vertex_id_t  rangelow = 0,
vertex_id_t  rangehigh = -1 
) [pure virtual]

Registers a sync with the engine.

Registers a sync with the engine. The sync will be performed approximately every "interval" updates, and will perform a reduction over all vertices from rangelow to rangehigh inclusive. The merge function may be NULL, in which it will not be used. However, it is highly recommended to provide a merge function since this allow the sync operation to be parallelized.

The sync operation is guaranteed to be strictly sequentially consistent with all other execution.

Parameters:
shared The shared variable to synchronize
sync The reduction function
apply The final apply function which writes to the shared value
zero The initial zero value passed to the reduction
sync_interval Frequency at which the sync is initiated. Corresponds approximately to the number of update function calls before the sync is reevaluated. If 0, the sync will only be evaluated once at engine start, and will never be evaluated again. Defaults to 0.
merge Combined intermediate reduction value. defaults to NULL. in which case, it will not be used.
rangelow he lower range of vertex id to start syncing. The range is inclusive. i.e. vertex with id 'rangelow' and vertex with id 'rangehigh' will be included. Defaults to 0.
rangehigh The upper range of vertex id to stop syncing. The range is inclusive. i.e. vertex with id 'rangelow' and vertex with id 'rangehigh' will be included. Defaults to infinity.
template<typename Graph>
virtual void graphlab::iengine< Graph >::set_task_budget ( size_t  max_tasks  )  [pure virtual]

set a limit on the number of tasks that may be executed.

By once the engine has achived the max_task parameter execution will be terminated. If max_tasks is set to zero then the task_budget is ignored. If max_tasks is greater than zero than the value of max tasks is used. Note that if max_task is nonzero the engine encurs the cost of an additional atomic operation in the main loop potentially reducing the overall parallel performance.

Implemented in graphlab::distributed_chromatic_engine< Graph >, graphlab::distributed_locking_engine< Graph, Scheduler >, graphlab::asynchronous_engine< Graph, Scheduler, ScopeFactory >, graphlab::distributed_chromatic_engine< distributed_graph >, graphlab::distributed_locking_engine< distributed_graph, Scheduler >, and graphlab::asynchronous_engine< graph, Scheduler, ScopeFactory >.

template<typename Graph>
virtual void graphlab::iengine< Graph >::start (  )  [pure virtual]
template<typename Graph>
virtual void graphlab::iengine< Graph >::stop (  )  [pure virtual]

Force engine to terminate immediately.

This function is used to stop the engine execution by forcing immediate termination. Any existing update tasks will finish but no new update tasks will be started and the call to start() will return.

Implemented in graphlab::distributed_chromatic_engine< Graph >, graphlab::distributed_locking_engine< Graph, Scheduler >, graphlab::asynchronous_engine< Graph, Scheduler, ScopeFactory >, graphlab::distributed_chromatic_engine< distributed_graph >, graphlab::distributed_locking_engine< distributed_graph, Scheduler >, and graphlab::asynchronous_engine< graph, Scheduler, ScopeFactory >.


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