MESH Kernel Functions. More...

#include <string.h>
#include <trash_stack.h>
#include <stdarg.h>
#include <gpriq.h>

Functions
void	g_slist_vsplit (GSList **src, GPFunc f, gpointer arg, int N,...)
	splits a list into N sublists using the partitioning function f, which takes two arguments: the list element to assign, and a user argument. N must be >= 2. The input list is destroyed.
void	g_slist_split (GSList *src, GPFunc f, gpointer arg, int N, GSList dest[])
	Splits a list into N sublists using the partitioning function f, which takes two arguments: the list element to assign, and a user argument. N must be >= 2. The input list is destroyed.
void	mesh_init (gint verbose)
	Initializes data structures for the MESH simulation. This function must be called before any other MESH functions.
void	mesh_load_config_file (gchar *config_file)
	Initializes MESH resources and schedulers based on the configuration file provided. Refer to the MESH User's Guide for configuration file format.
void	mesh_kernel ()
	Executes the MESH simulation. This function will not return until all threads of execution are done, or the simulation deadlocks.
mesh_feature_list *	mesh_create_feature_list ()
	Creates an empty feature list to be used when creating new resources.
mesh_feature_list *	mesh_feature_add (mesh_feature_list cfl, gchar feature, double power)
	Adds a named feature to the given feature list. A computation power is associated with the feature at add-time. This feature list should be used to describe a physical resource.
gint	mesh_get_feature_index_by_name (gchar *name)
	Searches the global feature list and returns the index into the list that corresponds to the feature name passed as an argument.
mesh_resource *	mesh_create_resource (gchar name, mesh_feature_list cfl, mesh_scheduler cs, double(timing_resolution)(mesh_resource , GSList ), double default_power)
	Creates a resource with a given name, accepted feature list of multi-dimensional consumes, a controlling scheduler, and a function that implements the resource behavior.
mesh_resource *	mesh_create_shared_resource (gchar name, mesh_feature_list cfl, double(timing_resolution)(mesh_resource , double ), void(contention)(mesh_resource , GSList , mesh_time), double default_power)
	Creates a shared resource with a given name, accepted feature list of multi- dimensional consumes, a controlling scheduler, and a function that implements the resource behavior. In addition, shared resources require a contention resolution function.
mesh_scheduler *	mesh_create_scheduler (gchar name, GSList (execute_scheduler)(mesh_scheduler ))
	Creates an execution scheduler and sets the scheduler functionality.
mesh_scheduler *	mesh_set_sched_resource (mesh_scheduler cs, mesh_resource cr)
	Sets the default resource to execute scheduler on for centralized scheduling strategies. If a centralized scheduling resource is not set, a scheduling strategy may assume distributed scheduling.
mesh_scheduler *	mesh_create_shared_scheduler (gchar name, void(execute_shared)(mesh_scheduler , GSList , mesh_time))
	Creates an shared resource scheduler and sets the scheduler functionality.
mesh_thread *	mesh_define_thread (gchar name, mesh_scheduler execution_scheduler, void (thread)(void ), void arg)
	Creates an execution thread but does not make it eligible for execution. To start the thread, use mesh start thread() and mesh start thread delayed().
void	mesh_start_thread (mesh_thread *thread)
	Once a thread is defined via mesh_define_thread(), this function will make the thread eligible for execution immediately.
void	mesh_start_thread_delayed (mesh_thread *thread)
	Once a thread is defined via mesh_define_thread(), this function will make the thread eligible for execution after the consume call is completed.
void	mesh_squash_thread (mesh_thread *ct)
	Immediately aborts and restarts a thread. All threads this one is joined on will also be squashed (ie comm call threads). Threads joined on this one will remain joined on the restarted thread.
mesh_scheduler *	mesh_get_scheduler_by_name (gchar *name)
	Finds the scheduler by its name and returns the pointer to it.
mesh_thread *	mesh_get_thread_by_name (gchar *name)
	Finds the thread by its name and returns the pointer to it.
void	mesh_cleanup ()
	Frees up all remaining data structures associated with MESH. Useful after executing mesh kernel.
mesh_time	mesh_getTime ()
	Finds the simulation time at the beginning of the currently executing consume block.
void	mesh_set_label_watch_output (gchar *filename)
	Sets the filename to output the label watch information. If this filename is left at NULL or the function not called at all, label watch information will be printed to STDOUT.
void	mesh_label_watch (gchar *name)
	Adds a consume label to a list to watch during the simulation execution. When a consume call with a label on the watch list is encountered, the timestamp and execution resource are printed to either a text file or STDOUT. Text file name can be specified with mesh_set_label_watch_output().}.
void	mesh_set_error (mesh_time error)
	Sets the error term to be used when creating timeslices in shared resource simulations. It determines how close consume call end-times can be and still be considered as one timeslice.
void	mesh_print_blocked_threads (gboolean flag)
	Sets whether a list of blocked threads will be printed out at the end of the simulation. This function is useful for finding deadlocked threads. It is set TRUE by default Must be called before mesh_kernel().
void	mesh_print_not_completed_threads (gboolean flag)
	Sets whether a list of threads that have not completed execution by the end of simulation will be printed. Not completed thread is defined as a thread that never returns from the function pointer provided to it in mesh_create_thread(). This function is useful to identify whether the simulation has ended sooner than expected (perhaps as a result of a deadlock). It is set FALSE by default Must be called before mesh_kernel().
void	mesh_print_thread_usage (gboolean flag)
	Sets whether a list of thread usage will be printed out at the end of the simulation. Must be called before mesh_kernel().
void	mesh_execute_at_commit (void(function)(mesh_consume_data ))
	Allows the user to add functionality to be executed after each consume block is committed. This is a very powerful extension allowing the user to extend the MESH simulator by adding additional functionality at every simulation time step. The added functionality has access to the mesh consume data structure that con- tains all the information about the consume block currently committed. The mesh execute at commit() can be run multiple times by appending more than one function to be executed.
void	mesh_execute_at_stall (void(function)(mesh_resource , mesh_thread *))
	Allows the user to add functionality to be executed when a thread stalls in its exe- cution e.g. due to synchronization. The added functionality has access to the thread that stalled and the resource it executed on. The mesh execute at stall() can be run multiple times by calling this function more than once with different function pointers.
void	mesh_execute_at_finish (void(function)(mesh_resource , mesh_thread *))
	Allows the user to add functionality to be executed when a thread finishes (there are no more executable statements in the thread) in its execution. The added func- tionality has access to the thread that finished and the resource it executed on. The mesh execute at finish() can be run multiple times by calling this function more than once with different function pointers.
void	mesh_execute_at_interrupt (void(function)(mesh_resource , mesh_thread *))
	adds a function to be executed when a resource (and possibly thread) is interrupted.
void	mesh_execute_at_squash (void(function)(mesh_resource , mesh_thread *))
	Allows the user to add functionality to be executed when the simulator squashes a thread (it will be automatically restarted). The added functionality has access to the thread that squashed and the resource it executed on. The mesh execute at squash() can be run multiple times by calling this function more than once with different function pointers.
void	mesh_scheduler_is_eligible (mesh_scheduler *cs)
	Ensures that a scheduler is on the kernel ``todo list.'' It will be called as long as there is at least one idle resource and one eligible thread available.
void	mesh_thread_is_eligible (mesh_thread *mt)
	makes sure thread is not already eligible, and adds it to the eligible list
void	mesh_thread_is_not_eligible (mesh_thread *mt)
	removes all instances of the given thread from the eligible list
mesh_time	mesh_thread_created_at (mesh_thread *ct)
	Retrieves the time the specified mesh thread was created.
mesh_time	mesh_thread_finished_at (mesh_thread *ct)
	Retrieves the time the specified mesh thread was finished.
void	mesh_create_interrupt (mesh_resource resource, gchar name, gboolean maskable, void (isr)(void ), void arg)
	Creates an interrupt on a resource. The resource must already have an interrupt controller.
void	mesh_set_interrupt_controller (mesh_resource resource, char ()(void , GSList *p), void arg)
	Sets an interrupt controller on a resource, allowing the creation and raising of interrupts. By default a resource has no interrupt controller (also achievable by passing a NULL controller arg) and will abort simulation if interrupts are used.
void	mesh_raise_interrupt (mesh_resource cr, gchar name)
	Raises an interrupt. If resource == NULL, use the resource the current thread is executing on. If the interrupt is not registered on the resource it will be ignored. The interrupt may not fire immediately it is currently disabled or another interrupt is already active.
void	mesh_disable_interrupt (gchar *name)
	Disables an interrupt. If name == NULL, all interrupts for the resource are disabled as a group. This does not change the enabled status of individual interrupts immediately it is currently disabled or another interrupt is already active.
void	mesh_enable_interrupt (gchar *name)
	Enables an interrupt. If name == NULL, all interrupts for the resource are enabled as a group. This does not change the enabled status of individual interrupts; those that have been disabled individually will remain so until they are explicitly re-enabled immediately it is currently disabled or another interrupt is already active.
gboolean	mesh_is_interrupt_enabled (gchar name, gboolean explicit, mesh_thread thread)
	Determines whether an interrupt is currently enabled for a thread. If no thread is given, use the one currently executing.

Detailed Description

MESH Kernel Functions.

Function Documentation

void g_slist_split	(	GSList **	src,
		GPFunc	f,
		gpointer	arg,
		int	N,
		GSList *	dest[]
	)

Splits a list into N sublists using the partitioning function f, which takes two arguments: the list element to assign, and a user argument. N must be >= 2. The input list is destroyed.

Parameters:

	src	Original list
	f	Partitioning function
	arg
	N	Number of sublists
	dest	Destination

Returns:

void g_slist_vsplit	(	GSList **	src,
		GPFunc	f,
		gpointer	arg,
		int	N,
			...
	)

splits a list into N sublists using the partitioning function f, which takes two arguments: the list element to assign, and a user argument. N must be >= 2. The input list is destroyed.

Parameters:

	src	Original list
	f	Partitioning function
	arg
	N	Number of sublists

Returns:

mesh_feature_list* mesh_create_feature_list ( )

Creates an empty feature list to be used when creating new resources.

See also:: mesh create scheduler(), mesh create thread()

Parameters:

N

Number of sublists

Returns:: Pointer to new feature list

void mesh_create_interrupt	(	mesh_resource *	cr,
		gchar *	name,
		gboolean	maskable,
		void ()(void *)	isr,
		void *	arg
	)

Creates an interrupt on a resource. The resource must already have an interrupt controller.

Parameters:

	cr	Resource to create interrupt on
	name	Interrupt name
	maskable	Maskable status of interrupt (Not yet supported
	isr	Interrupt service routine. Supply NULL if none required
	arg	Argument passed to ISR

See also:: mesh set interrupt controller(), mesh raise interrupt()

Returns:: none.

mesh_resource* mesh_create_resource	(	gchar *	name,
		mesh_feature_list *	cfl,
		mesh_scheduler *	cs,
		double()(mesh_resource , GSList *)	timing_resolution,
		double	default_power
	)

Creates a resource with a given name, accepted feature list of multi-dimensional consumes, a controlling scheduler, and a function that implements the resource behavior.

Parameters:

	name	Name of resource
	cfl	List of consume features that the resource accepts
	scheduler	Scheduler tied to the resource
	(timing*	resolution) Function pointer to the function that implements the resolution of consume fea- tures onto physical timing for this particular resource. Should pass a pointer to the resource executing the consume call, and a pointer to the list of consume call feature arrays.
	default	power Computational power associated with the default feature

Returns:: Pointer to new resource

See also:: mesh create scheduler(), mesh create thread()

mesh_scheduler* mesh_create_scheduler	(	gchar *	name,
		GSList ()(mesh_scheduler *)	execute_scheduler
	)

Creates an execution scheduler and sets the scheduler functionality.

Parameters:

	name	Name of scheduler
	(exec*	scheduler) Function pointer to the function that implements the scheduler functionality. Accepts a pointer to the scheduler and returns a list of thread/resource pairs to be run.

Returns:: Pointer to new scheduler

See also:: mesh create shared scheduler()

mesh_resource* mesh_create_shared_resource	(	gchar *	name,
		mesh_feature_list *	cfl,
		double()(mesh_resource , double *)	timing_resolution,
		void()(mesh_resource , GSList *, mesh_time)	contention,
		double	default_power
	)

Creates a shared resource with a given name, accepted feature list of multi- dimensional consumes, a controlling scheduler, and a function that implements the resource behavior. In addition, shared resources require a contention resolution function.

Parameters:

	name	Name of resource
	feature	list List of consume features that the resource accepts
	scheduler	Scheduler tied to the resource
	(timing*	resolution) Function pointer to the function that implements the resolution of consume features onto physical timing for this particular resource. Should pass a pointer to the resource executing the consume call, pointer to the consume data structure and the current simulation time.
	(contention)*	Function that determines how much of a penalty should be applied given various physical usage times and a timeslice duration. default power Computational power associated with the default feature

Returns:: Pointer to new resource

See also:: mesh create scheduler(), mesh create thread()

mesh_scheduler* mesh_create_shared_scheduler	(	gchar *	name,
		void()(mesh_scheduler , GSList *, mesh_time)	execute_shared
	)

Creates an shared resource scheduler and sets the scheduler functionality.

Parameters:

	name	Name of the scheduler
	(exec*	shared) Function pointer to the function that implements the shared scheduler functionality. Accepts a list of shared resource accesses during the current time period.

Returns:: Pointer to new scheduler

See also:: mesh create scheduler()

mesh_thread* mesh_define_thread	(	gchar *	name,
		mesh_scheduler *	execution_scheduler,
		void ()(void *)	thread,
		void *	arg
	)

Creates an execution thread but does not make it eligible for execution. To start the thread, use mesh start thread() and mesh start thread delayed().

Parameters:

	name	Name of the thread
	*exec	scheduler Execution scheduler that handles the consume calls of this thread.
	(thread)*	Function pointer to the function that implements the thread functionality.
	arg	Argument to pass to the new thread

Returns:: Pointer to new thread

See also:: mesh start thread(), mesh start thread delayed()

void mesh_disable_interrupt ( gchar * name )

Disables an interrupt. If name == NULL, all interrupts for the resource are disabled as a group. This does not change the enabled status of individual interrupts immediately it is currently disabled or another interrupt is already active.

Parameters:

name

Interrupt to raise

void mesh_enable_interrupt ( gchar * name )

Enables an interrupt. If name == NULL, all interrupts for the resource are enabled as a group. This does not change the enabled status of individual interrupts; those that have been disabled individually will remain so until they are explicitly re-enabled immediately it is currently disabled or another interrupt is already active.

Parameters:

name

Interrupt to raise

mesh_feature_list* mesh_feature_add	(	mesh_feature_list *	cfl,
		gchar *	feature,
		double	power
	)

Adds a named feature to the given feature list. A computation power is associated with the feature at add-time. This feature list should be used to describe a physical resource.

Parameters:

	*cfl	Feature list to add to
	*feature	Name of feature to add
	power	Computational power to associate with this feature

Returns:: New feature list with feature added

See also:: mesh create feature list(), mesh create resource()

gint mesh_get_feature_index_by_name ( gchar * name )

Searches the global feature list and returns the index into the list that corresponds to the feature name passed as an argument.

Parameters:

name

Name of feature

Returns:: Integer index into a global feature list

mesh_scheduler* mesh_get_scheduler_by_name ( gchar * name )

Finds the scheduler by its name and returns the pointer to it.

Parameters:

name

Name of the scheduler

Returns:: Pointer to desired scheduler, NULL if not found

See also:: mesh_get_thread_by_name()

mesh_thread* mesh_get_thread_by_name ( gchar * name )

Finds the thread by its name and returns the pointer to it.

Parameters:

name

Name of the thread

Returns:: Pointer to desired thread, NULL if not found

See also:: mesh_get_scheduler_by_name()

mesh_time mesh_getTime ( )

Finds the simulation time at the beginning of the currently executing consume block.

Returns:: Begin time of currently executing consume block

void mesh_init ( gint verbose )

Initializes data structures for the MESH simulation. This function must be called before any other MESH functions.

Parameters:

verbose

Verbosity of simulator, 0 means no extra messages, 1 displays large volumes of information

See also:: mesh_kernel(), mesh_cleanup()

gboolean mesh_is_interrupt_enabled	(	gchar *	name,
		gboolean	explicit,
		mesh_thread *	thread
	)

Determines whether an interrupt is currently enabled for a thread. If no thread is given, use the one currently executing.

Parameters:

	name	Interrupt to check, use NULL to test if interrupts are globally disabled
	explicit	determine whether the interrupt can fire
	thread	thread to check

void mesh_kernel ( )

Executes the MESH simulation. This function will not return until all threads of execution are done, or the simulation deadlocks.

See also:: mesh_init(), mesh_cleanup()

void mesh_label_watch ( gchar * name )

Adds a consume label to a list to watch during the simulation execution. When a consume call with a label on the watch list is encountered, the timestamp and execution resource are printed to either a text file or STDOUT. Text file name can be specified with mesh_set_label_watch_output().}.

Parameters:

name

Name of consume annotation label to add to the watch list

See also:: mesh_set_label_watch_output()

void mesh_load_config_file ( gchar * config_file )

Initializes MESH resources and schedulers based on the configuration file provided. Refer to the MESH User's Guide for configuration file format.

Parameters:

config_file

MESH Configuration file

void mesh_print_blocked_threads ( gboolean flag )

Sets whether a list of blocked threads will be printed out at the end of the simulation. This function is useful for finding deadlocked threads. It is set TRUE by default Must be called before mesh_kernel().

Parameters:

flag

True or False

See also:: mesh_print_not_completed_flag()

void mesh_print_not_completed_threads ( gboolean flag )

Sets whether a list of threads that have not completed execution by the end of simulation will be printed. Not completed thread is defined as a thread that never returns from the function pointer provided to it in mesh_create_thread(). This function is useful to identify whether the simulation has ended sooner than expected (perhaps as a result of a deadlock). It is set FALSE by default Must be called before mesh_kernel().

Parameters:

flag

True or False

See also:: mesh_print_not_completed_flag()

void mesh_print_thread_usage ( gboolean flag )

Sets whether a list of thread usage will be printed out at the end of the simulation. Must be called before mesh_kernel().

Parameters:

flag

True or False

See also:: mesh_print_not_completed_flag()

void mesh_raise_interrupt	(	mesh_resource *	cr,
		gchar *	name
	)

Raises an interrupt. If resource == NULL, use the resource the current thread is executing on. If the interrupt is not registered on the resource it will be ignored. The interrupt may not fire immediately it is currently disabled or another interrupt is already active.

Parameters:

	cr	Resource to raise interrupt on
	name	Interrupt to raise

void mesh_scheduler_is_eligible ( mesh_scheduler * cs )

Ensures that a scheduler is on the kernel ``todo list.'' It will be called as long as there is at least one idle resource and one eligible thread available.

fn mesh_scheduler_is_eligible(mesh_scheduler *cs)

Parameters:

cs

Scheduler to run

Returns:: The kernel thread

void mesh_set_error ( mesh_time error )

Sets the error term to be used when creating timeslices in shared resource simulations. It determines how close consume call end-times can be and still be considered as one timeslice.

Parameters:

error

Maximum distance between consume events to be combined

mesh_set_interrupt_controller	(	mesh_resource *	resource,
		char *	)(void , GSList **p,
		void *	arg
	)

Sets an interrupt controller on a resource, allowing the creation and raising of interrupts. By default a resource has no interrupt controller (also achievable by passing a NULL controller arg) and will abort simulation if interrupts are used.

Parameters:

	cr	Resource to set interrupt controller on
	controller	Interrupt controller to use
	arg	User data arg to pass to the controller

void mesh_set_label_watch_output ( gchar * filename )

Sets the filename to output the label watch information. If this filename is left at NULL or the function not called at all, label watch information will be printed to STDOUT.

Parameters:

filename

Name of file to redirect label watch output

mesh_scheduler* mesh_set_sched_resource	(	mesh_scheduler *	cs,
		mesh_resource *	cr
	)

Sets the default resource to execute scheduler on for centralized scheduling strategies. If a centralized scheduling resource is not set, a scheduling strategy may assume distributed scheduling.

Parameters:

	scheduler	Already created scheduler whose execution needs to be changed
	resource	Pointer to the resource which will execute this scheduler precond mesh_create_scheduler() must be run to create a scheduler first

Returns:: Pointer to the adjusted scheduler.

void mesh_squash_thread ( mesh_thread * ct )

Immediately aborts and restarts a thread. All threads this one is joined on will also be squashed (ie comm call threads). Threads joined on this one will remain joined on the restarted thread.

Parameters:

ct

Thread to squash

void mesh_start_thread ( mesh_thread * thread )

Once a thread is defined via mesh_define_thread(), this function will make the thread eligible for execution immediately.

Parameters:

thread

Thread to make eligible for execution

void mesh_start_thread_delayed ( mesh_thread * thread )

Once a thread is defined via mesh_define_thread(), this function will make the thread eligible for execution after the consume call is completed.

Parameters:

thread

Thread to make eligible for execution

mesh_time mesh_thread_created_at ( mesh_thread * ct )

Retrieves the time the specified mesh thread was created.

fn mesh_thread_created_at(mesh_thread *ct);

Parameters:

ct

thread to get time

Returns:: time

See also:: mesh_current_thread()

mesh_time mesh_thread_finished_at ( mesh_thread * ct )

Retrieves the time the specified mesh thread was finished.

fn mesh_thread_finished_at(mesh_thread *ct);

Parameters:

ct

thread to get time

Returns:: time

See also:: mesh_current_thread()

void mesh_thread_is_eligible ( mesh_thread * mt )

makes sure thread is not already eligible, and adds it to the eligible list

fn mesh_thread_is_eligible(mesh_thread *mt)

Parameters:

mt

thread

Returns:: The kernel thread

void mesh_thread_is_not_eligible ( mesh_thread * mt )

removes all instances of the given thread from the eligible list

fn mesh_thread_is_not_eligible(mesh_thread *mt)

Parameters:

mt

thread

Returns:: The kernel thread

/home/mesh/mesh/include/mesh_kernel.h File Reference

Functions

Detailed Description

Function Documentation