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 >:

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 metrics graphlab::iengine< Graph >::get_metrics ( ) [inline, virtual]

Return the metrics information logged by the engine.

See also:: dump_metrics reset_metrics

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 360 of file iengine.hpp.

template<typename Graph>

virtual exec_status graphlab::iengine< Graph >::last_exec_status ( ) const [pure virtual]

Describe the reason for termination.

Return the reason for the last termination.

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 size_t graphlab::iengine< Graph >::last_update_count ( ) const [pure virtual]

Get the number of updates executed by the engine.

This function returns the numbe of updates executed by the last run of this engine.

Returns:: the total number of updates

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 >::register_monitor ( imonitor_type * listener ) [pure virtual]

Register a monitor with an engine.

A monitor tracks the execution of an engine can be useful when debugging.

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

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 >::reset_metrics ( ) [inline, virtual]

Clears all logged metrics

See also:: dump_metrics get_metrics

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 368 of file iengine.hpp.

template<typename Graph>

virtual void graphlab::iengine< Graph >::set_cpu_affinities ( bool value ) [inline, virtual]

Set whether cpu affinities should be used.

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 260 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]

Set the default scope range.

The default scope range determines the locking extent of an update function. See Scopes for details.

Parameters:

default_scope_range

can take on any of the values described in scope_range

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 >::set_sched_yield ( bool value ) [inline, virtual]

Set whether sched yield should be used when waiting on new jobs

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

Definition at line 255 of file iengine.hpp.

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]

Start the engine execution.

This blocking function starts the engine and does not return until either one of the termination conditions evaluate true or the scheduler has no tasks remaining.

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

template<typename Graph>

virtual void graphlab::iengine< Graph >::sync_now ( glshared_base & shared ) [pure virtual]

Performs a sync immediately. This function requires that the shared variable already be registered with the engine.

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:

src/graphlab/engine/iengine.hpp

graphlab::iengine< Graph > Class Template Reference

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

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

Member Typedef Documentation

Member Function Documentation

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