The context object mediates the interaction between the vertex program and the graphlab execution environment. More...

#include <graphlab/vertex_program/icontext.hpp>

Public Types
typedef GraphType	graph_type
	the user graph type (typically distributed_graph)
typedef graph_type::vertex_type	vertex_type
	the opaque vertex_type defined in the ivertex_program::graph_type (typically distributed_graph::vertex_type)
typedef graph_type::vertex_id_type	vertex_id_type
	the global vertex identifier (see graphlab::vertex_id_type).
typedef MessageType	message_type
typedef GatherType	gather_type

Public Member Functions
virtual	~icontext ()
	icontext destructor
virtual size_t	num_vertices () const
	Get the total number of vertices in the graph.
virtual size_t	num_edges () const
	Get the number of edges in the graph.
virtual size_t	procid () const
	Get the id of this process.
virtual std::ostream &	cout () const
	Returns a standard output object (like cout) which only prints once even when running distributed.
virtual std::ostream &	cerr () const
	Returns a standard error object (like cerr) which only prints once even when running distributed.
virtual size_t	num_procs () const
	Get the number of processes in the current execution.
virtual float	elapsed_seconds () const
	Get the elapsed time in seconds since start was called.
virtual int	iteration () const
	Return the current interation number (if supported).
virtual void	stop ()
	Signal the engine to stop executing additional update functions.
virtual void	signal (const vertex_type &vertex, const message_type &message=message_type())
	Signal a vertex with a particular message.
virtual void	signal_vid (vertex_id_type gvid, const message_type &message=message_type())
	Send a message to a vertex ID.
virtual void	post_delta (const vertex_type &vertex, const gather_type &delta)
	Post a change to the cached sum for the vertex.
virtual void	clear_gather_cache (const vertex_type &vertex)
	Invalidate the cached gather on the vertex.

Detailed Description

template<typename GraphType, typename GatherType, typename MessageType>
class graphlab::icontext< GraphType, GatherType, MessageType >

The context object mediates the interaction between the vertex program and the graphlab execution environment.

Each of the vertex program (see ivertex_program) methods is passed a reference to the engine's context. The context allows vertex programs to access information about the current execution and send information (through icontext::signal, icontext::post_delta, and icontext::clear_gather_cache) to the graphlab engines (see iengine).

Template Parameters:

GraphType	the type of graph (typically distributed_graph)
GatherType	the user defined gather type (see ivertex_program::gather_type).
MessageType	the user defined message type (see ivertex_program::message_type).

Definition at line 57 of file icontext.hpp.

Member Typedef Documentation

template<typename GraphType, typename GatherType, typename MessageType>

typedef GatherType graphlab::icontext< GraphType, GatherType, MessageType >::gather_type

The type returned by the gather operation. (see ivertex_program::gather_type)

Reimplemented in graphlab::context< Engine >.

Definition at line 88 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

typedef MessageType graphlab::icontext< GraphType, GatherType, MessageType >::message_type

The message type specified by the user-defined vertex-program. (see ivertex_program::message_type)

Reimplemented in graphlab::context< Engine >.

Definition at line 82 of file icontext.hpp.

Member Function Documentation

template<typename GraphType, typename GatherType, typename MessageType>

virtual std::ostream& graphlab::icontext< GraphType, GatherType, MessageType >::cerr ( ) const

inlinevirtual

Returns a standard error object (like cerr) which only prints once even when running distributed.

This returns a C++ standard output stream object which maps directly to std::cerr on machine with process ID 0, and to empty output streamss on all other processes. Calling,

context.cerr() << "Hello World!";

will therefore only print if the code is run on machine 0. This is useful in the finalize operation in aggregators.

Reimplemented in graphlab::context< Engine >.

Definition at line 153 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual void graphlab::icontext< GraphType, GatherType, MessageType >::clear_gather_cache ( const vertex_type & vertex )

inlinevirtual

Invalidate the cached gather on the vertex.

When caching is enabled clear_gather_cache clears the cache entry forcing a complete invocation of the subsequent gather.

Parameters:

vertex [in] the vertex whose cache to clear.

Reimplemented in graphlab::context< Engine >.

Definition at line 265 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual std::ostream& graphlab::icontext< GraphType, GatherType, MessageType >::cout ( ) const

inlinevirtual

Returns a standard output object (like cout) which only prints once even when running distributed.

This returns a C++ standard output stream object which maps directly to std::cout on machine with process ID 0, and to empty output streamss on all other processes. Calling,

context.cout() << "Hello World!";

will therefore only print if the code is run on machine 0. This is useful in the finalize operation in aggregators.

Reimplemented in graphlab::context< Engine >.

Definition at line 137 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual float graphlab::icontext< GraphType, GatherType, MessageType >::elapsed_seconds ( ) const

inlinevirtual

Get the elapsed time in seconds since start was called.

Returns:: runtine in seconds

Reimplemented in graphlab::context< Engine >.

Definition at line 173 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual int graphlab::icontext< GraphType, GatherType, MessageType >::iteration ( ) const

inlinevirtual

Return the current interation number (if supported).

Returns:: the current interation number if support or -1 otherwise.

Reimplemented in graphlab::context< Engine >.

Definition at line 181 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual size_t graphlab::icontext< GraphType, GatherType, MessageType >::num_edges ( ) const

inlinevirtual

Get the number of edges in the graph.

Each direction counts as a separate edge.

Returns:: the total number of edges in the entire graph.

Reimplemented in graphlab::context< Engine >.

Definition at line 109 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual size_t graphlab::icontext< GraphType, GatherType, MessageType >::num_procs ( ) const

inlinevirtual

Get the number of processes in the current execution.

This is typically the number of mpi jobs created:

%> mpiexec -n 16 ./pagerank

would imply that num_procs() returns 16.

Returns:: the number of processes in the current execution

Reimplemented in graphlab::context< Engine >.

Definition at line 166 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual size_t graphlab::icontext< GraphType, GatherType, MessageType >::num_vertices ( ) const

inlinevirtual

Get the total number of vertices in the graph.

Returns:: the total number of vertices in the entire graph.

Reimplemented in graphlab::context< Engine >.

Definition at line 100 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual void graphlab::icontext< GraphType, GatherType, MessageType >::post_delta	(	const vertex_type &	vertex,
		const gather_type &	delta
	)

inlinevirtual

Post a change to the cached sum for the vertex.

Often a vertex program will be signaled due to a change in one or a few of its neighbors. However the gather operation will be rerun on all neighbors potentially producing the same value as previous invocations and wasting computation time. To address this some engines support caching (see gather_caching for details) of the gather phase.

When caching is enabled the engines save a copy of the previous gather for each vertex. On subsequent calls to gather if their is a cached gather then the gather phase is skipped and the cached value is passed to the ivertex_program::apply function. Therefore it is the responsibility of the vertex program to update the cache values for neighboring vertices. This is accomplished by using the icontext::post_delta function. Posted deltas are atomically added to the cache.

Parameters:

vertex	[in] the vertex whose cache we want to update
delta	[in] the change that we want to add to the current cache.

Definition at line 254 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual size_t graphlab::icontext< GraphType, GatherType, MessageType >::procid ( ) const

inlinevirtual

Get the id of this process.

The procid is a number between 0 and graphlab::icontext::num_procs

Warning:: Each process may have many threads

Returns:: the process of this machine.

Reimplemented in graphlab::context< Engine >.

Definition at line 121 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual void graphlab::icontext< GraphType, GatherType, MessageType >::signal	(	const vertex_type &	vertex,
		const message_type &	message = `message_type()`
	)

inlinevirtual

Signal a vertex with a particular message.

This function is an essential part of the GraphLab abstraction and is used to encode iterative computation. Typically a vertex program will signal neighboring vertices during the scatter phase. A vertex program may choose to signal neighbors on when changes made during the previos phases break invariants or warrant future computation on neighboring vertices.

The signal function takes two arguments. The first is mandatory and specifies which vertex to signal. The second argument is optional and is used to send a message. If no message is provided then the default message is used.

Parameters:

vertex	[in] The vertex to send the message to
message	[in] The message to send, defaults to message_type().

Definition at line 213 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual void graphlab::icontext< GraphType, GatherType, MessageType >::signal_vid	(	vertex_id_type	gvid,
		const message_type &	message = `message_type()`
	)

inlinevirtual

Send a message to a vertex ID.

Warning:: This function will be slow since the current machine do not know the location of the vertex ID. If possible use the the icontext::signal call instead.

Parameters:

gvid	[in] the vertex id of the vertex to signal
message	[in] the message to send to that vertex, defaults to message_type().

Definition at line 227 of file icontext.hpp.

template<typename GraphType, typename GatherType, typename MessageType>

virtual void graphlab::icontext< GraphType, GatherType, MessageType >::stop ( )

inlinevirtual

Signal the engine to stop executing additional update functions.

Warning:: The execution engine will stop eventually and additional update functions may be executed prior to when the engine stops. For-example the synchronous engine (see synchronous_engine) will complete the current super-step before terminating.

Reimplemented in graphlab::context< Engine >.

Definition at line 193 of file icontext.hpp.

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

graphlab/vertex_program/icontext.hpp

Public Types

Public Member Functions

Detailed Description

template<typename GraphType, typename GatherType, typename MessageType> class graphlab::icontext< GraphType, GatherType, MessageType >

Member Typedef Documentation

Member Function Documentation

template<typename GraphType, typename GatherType, typename MessageType>
class graphlab::icontext< GraphType, GatherType, MessageType >