Download AYUDAME User Manual

Ayudame
communication for StarSs
Steffen Brinkmann
HLRS, Universit¨at Stuttgart
2
Disclaimer: The information contained in this manual is not garanteed to be complete
at this stage. It is subject to changes without further notice. Please send comments,
corrections and additional text to [email protected].
Steffen Brinkmann:Ayudame- communication for StarSs, manual for the communication library Ayudame.
Revision history:
Version
1.0
Date
6 Sep 2012
Remarks
initial version
Author
Steffen Brinkmann
c 2009-2012, HLRS, University of Stuttgart, all rights reserved.
Redistribution and use in source (SGML DocBook) and ’compiled’ forms (SGML, HTML, PDF,
PostScript, RTF and so forth) with or without modification, are permitted provided that the following
conditions are met:
Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of
conditions and the following disclaimer as the first lines of this file unmodified.
Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF
and other formats) must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDER ”AS IS” AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
Ayudame
Contents
1. Introduction
5
2. Quick start guides
2.1. For application programmers . . . . . . . . . . . . . . . . . . . . . . . . .
2.2. For runtime programmers . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
5
5
3. Events and requests
7
3.1. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2. Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4. The callback functions
11
4.1. The AYU event callback function . . . . . . . . . . . . . . . . . . . . . . . 11
A. Sources
11
A.1. The header Ayudame.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5
1. Introduction
Ayudame is a generic library for communicating events occuring while running a StarSs
task parallel application to the outside. The present version will set up a tcp/ip socket
server, wait for a client to connect and send messages to it. A client designed to work
with Ayudame is Temanejo.
2. Quick start guides
2.1. For application programmers
In order to use Ayudame you will have to compile the library. This is done with
shell: Ayudame directory
# make && make install
This compiles the library and creates a link to it in the directory ¡ayudame directory¿/lib.
If you encounter problems please read the README file in the Ayudame directory and
the comments in the Makefile.
To execute an application with Ayudame enabled, run it as follows:
shell: Ayudame directory
# LD_PRELOAD=<ayudame_directory>/lib/libayudame.so ./application <parameters>
The application will run until the start of the task parallel part. It will then pause and
wait for a client (e.g. Temanejo) to connect. Then it will wait until a ”step” request
is issued by the client which is done by pressing the ”Play” button in Temanejo.
2.2. For runtime programmers
In order to connect to programmes like Temanejo, the StarSs runtime has to call the
AYU event callback function. This function will send the appropriate message depending
on the input parameters. Generally a call to AYU event looks like this:
C example: call to AYU event
#if USE_AYUDAME
if (AYU_event) AYU_event(<event_id>, <task_id>, <void_data_pointer>);
#endif
The statement is enclosed in a preprocessor directive in order to be able to switch the
Ayudame support of when compiling the runtime. It is suggested to do so and to set
USE AYUDAME while configuring the runtime (when using autotools).
Furthermore the statement is only executed if an implementation of AYU event is
found at execution time. For details see sec. 4.
The event id indicates which type of event is being communicated. It is an integer
of type enum ayu event t declared in the header Ayudame.h:
Steffen Brinkmann - HLRS, Universit¨at Stuttgart
6
2 Quick start guides
C example: event id enum
enum ayu_event_t {
AYU_EVENT_NULL = 0,
AYU_PREINIT = 1,
AYU_INIT = 2,
AYU_FINISH = 3,
AYU_REGISTERFUNCTION = 4,
AYU_ADDTASK = 5,
AYU_ADDHIDDENTASK = 6,
AYU_ADDDEPENDENCY = 7,
AYU_ADDTASKTOQUEUE = 8,
AYU_PRESELECTTASK = 9,
AYU_PRERUNTASK = 10,
AYU_RUNTASK = 11,
AYU_POSTRUNTASK = 12,
AYU_RUNTASKFAILED = 13,
AYU_REMOVETASK = 14,
AYU_WAITON = 15,
AYU_BARRIER = 16,
AYU_ADDWAITONTASK = 17
};
Not all of these events are necessary. A minimalistic sequence of events could look
like this:
C example: minimalistic example
1
2
3
4
5
6
7
8
9
#include <Ayudame.h>
ayu_runtime_t ayu_rt = AYU_RT_OMPSS; //for OMPSs runtime
AYU_event(AYU_PREINIT, 0, (void*) &ayu_rt );
int64_t AYU_data1[2] = { function_id_1, task_is_critical_1 };
AYU_event(AYU_ADDTASK, 1, AYU_data1);
int64_t AYU_data2[2] = { function_id_2, task_is_critical_2 };
AYU_event(AYU_ADDTASK, 2, AYU_data2);
uintptr_t Ayu_data3[3] = { 1, mem_address, original_mem_address };
AYU_event(AYU_ADDDEPENDENCY, 2, AYU_data3);
Please note that Ayudame.h has to be in the include path and that for easier readability
the checks of the form if (AYU event) were omitted. Thus this code will only work if
libayudame.so is preloaded.
Let us step through the example above. In line 1 the header Ayudame.h is included.
This is necessary for providing the declarations of the callback functions and the event
enum type. In line 2 a variable of type ayu runtime t is declared and defined to hold an
identifier for the runtime. These identifiers are declared in Ayudame.h (see Appendix).
In line 3 AYU event is called for the first time with the event id AYU PREINIT. When this
event is sent, Ayudame will set up the socket server and wait for a client to connect.
The port of the socket connection is set by the environment variable AYU PORT. If this
Ayudame
7
variable is not defined, the port is set to
port = pid % 1000 + 5000,
i.e. for a process id of 23674, the port will result in 5674.
In line 4 the additional data is set up for adding a task to the dependency graph. It
consists of the function id of the task and an integer indicating whether the task is to
be executed with priority (1) or not (0).
In the next line (4) the creation of the task is
communicated to Ayudame. The function parameters are the type of the event (AYU ADDTASK), the
task id (1) and the additional data. We repeat the
last to steps for another task with the task id 2.
Finally we define a dependency between these
tasks in lines 8 and 9. Here the additional data consists of the task id of the task which “causes” the
dependency, the memory address of the dependency
and (in the case of renaming, see SMPSs manual)
the original memory address.
The call to AYU event contains the type of event
AYU ADDDEPENDENCY, the task id of the task “suffer- Figure 1: minimalistic example graph
ing” the dependency and the additional data.
This piece of code will result in a dependency graph shown in figure 1.
3. Events and requests
Genrally speaking the interactions of Ayudame with the world can be divided into two
types: events and requests. Events represent the information flow from the application
and the runtime environment to the outside world (e.g. a file, a logging tool or a
debugger) while requests are passed from the outside world to the application.
The events are handled runtime-independant by the AYU event() callback function.
Requests on the other hand are highly runtime dependant. The set of available request
varies strongly from one runtime to the other.
3.1. Events
Events are communicated by the use of the AYU event() callback function. It is declared
in Ayudame.h as follows:
1
2
void AYU event ( a y u e v e n t t event , const i n t 6 4 t t a s k I d , void ∗p )
attribute
( ( weak ) ) ;
This declaration permits to leave the header included even if the library libayudame.so
is not linked or preloaded. In that case the callback name AYU event is equivalent to
false. Therefore it is recommended to call this function within a conditional clause:
Steffen Brinkmann - HLRS, Universit¨at Stuttgart
8
1
3 Events and requests
i f ( AYU event ) AYU event (AYU ADDTASK, 1 , Ayu data ) ;
The parameters passed to AYU event consist in an event type, a task id and additional
data the content of which depends on the event type. Three events are mandatory for
building the graph: AYU PREINIT, AYU ADDTASK and AYU ADDDEPENDENCY.
Find a comprehensive list of events in following:
AYU EVENT NULL: dummy event
optional for initialisation of event variables, event Id: 0
Does not represent an event.
AYU PREINIT: Pre-initialisation
mandatory for logging, event Id: 1
Should latest be emmited just before the parallel execution starts. Must be the first
event to be emitted.
The additional data must be a pointer to an integer denoting which runtime is in use:
CppSs (1), SMPSs (2), OMPSs (3), GOMP (4) or (CILK).
a y u r u n t i m e t a y u r t = AYU RT SMPSS ;
i f ( AYU event ) { AYU event (AYU PREINIT , 0 , ( void ∗ ) &a y u r t ) ; }
AYU INIT: Initialisation
optional for logging, event Id: 2
Should be sent just after AYU PREINIT. The execution will pause if pausing is available
for the specified runtime until a request is received in order to proceed to execute the
parallel part of the application.
i f ( AYU event ) { AYU event ( AYU INIT , 0 , NULL ) ; }
AYU FINISH: Finalisation
recommended for closing socket connection, event Id: 3
This event notifies that the parallel part of the application has finished. The socket
connection will be closed.
i f ( AYU event ) {AYU event ( AYU FINISH , 0 , NULL ) ; }
AYU REGISTERFUNCTION: Register taskified functions
optional for function name display, event Id: 4
This event registers the function name and the function Id of a taskified function.
i f ( AYU event ) { AYU event (AYU REGISTERFUNCTION, 0 , ( void ∗ ) name ) ; }
Ayudame
3.1
Events
9
AYU ADDTASK: Create task
mandatory for graph display, event Id: 5
A task is represented by a node in the dependency graph. When a task is created a
notification should be emitted containing the task Id and the function Id of the function
executed by the task. It is recommended to either make sure that every function is
registered before the first task for this function is created, or not to register function
names at all.
The additional data must be a pointer to an integer denoting whether the task is
critical (high-priority, =1) or not (=0).
i n t 6 4 t AYU data [ 2 ] = { f u n c t i o n I d , ( int ) task −>i s C r i t i c a l ( ) } ;
i f ( AYU event ) { AYU event (AYU ADDTASK, task −>g e t I d ( ) , AYU data ) ; }
AYU ADDHIDDENTASK: Add hidden task
do not use, development in progress, event Id: 6
Do not use! This is under development!
AYU ADDDEPENDENCY: Define dependency
mandatory for graph display, event Id: 7
A dependency is represented by an edge in the dependency graph. When a dependency
is created, the application should notify that passing along the task Id of the predecessor,
the memory address of the variable or array causing the dependency and the original
memory address of the variable (in case of renaming). The address can be 0 if unknown.
It is necessary that both tasks (the dependant and the task it depends on) are already
created when defining a dependency.
u i n t p t r t Ayu data [ 3 ] = { 0 , 0 , 0 } ;
Ayu data [ 0 ] = otherTask−>g e t I d ( ) ;
Ayu data [ 1 ] = mem addr of dependecy ;
Ayu data [ 2 ] = o r i g i n a l m e m a d d r o f d e p e n d e c y ;
i f ( AYU event ) {
AYU event (AYU ADDDEPENDENCY, task −>g e t I d ( ) , ( void ∗ ) Ayu data ) ;
}
AYU ADDTASKTOQUEUE: Queue task notification
recommended for graph display, event Id: 8
When a task does not depend on any other tasks it can be marked as queued. The task
must exist prior to this event. Additionally the Id of the thread which queued the task
can be passed.
i n t p t r t t h i d=getThreadId ( ) ;
i f ( AYU event ) {
Steffen Brinkmann - HLRS, Universit¨at Stuttgart
10
3 Events and requests
AYU event (AYU ADDTASKTOQUEUE, task −>g e t I d ( ) , &t h r e a d i d ) ;
}
AYU PRESELECTTASK: Task is about to be dequeued
do not use, debugging event, event Id: 9
This event notifies that the runtime is checking the queue(s) for a task to run. As this
event will usually occur many times, it is completely ignored, i.e. not even logged.
AYU PRERUNTASK: Prerun task notification
recommended for graph display, event Id: 10
When a task is scheduled for execution, i.e. an execution thread has dequeued the task
it can be marked as “about to run”. This event is recommended to be emitted before
pausing the execution when stepping through the dependency graph.
The number of nodes marked this way is at any time equal or less the number of
execution threads. Additionally the Id of the thread which runs the task can be passed.
i n t p t r t t h i d=getThreadId ( ) ;
i f ( AYU event ) {
AYU event (AYU PRERUNTASK, task −>g e t I d ( ) , &t h r e a d i d ) ;
}
AYU RUNTASK: Run task notification
optional for time measurement, event Id: 11
Just before the task is executed a “run task” event can be emitted. This event is intended
for time measurement. Between this event and the actual execution of the task there
should be as less code as possible to ensure exact time stamps.
i f ( AYU event )
{ AYU event (AYU RUNTASK, task −>g e t I d ( ) , NULL ) ; }
AYU POSTRUNTASK: Task execution finished
optional for logging, event Id: 12
i f ( AYU event ) { AYU event (AYU POSTRUNTASK, task −>g e t I d ( ) , NULL ) ; }
AYU RUNTASKFAILED: Task execution failed
optional for failed tasks, event Id: 13
i f ( AYU event ) { AYU event (AYU RUNTASKFAILED, task −>g e t I d ( ) , NULL ) ; }
Ayudame
3.2
Requests
11
AYU REMOVETASK: Task execution finished
recommended for graph display and time measurement, event Id: 14
When a task has finished this event should be emitted.
i f ( AYU event ) { AYU event (AYU REMOVETASK, taskNode−>g e t I d ( ) , NULL ) ; }
AYU WAITON: Wait-on event
do not use, development in progress, event Id: 15
For treating wait-on events.
Do not use! This is under development!
AYU BARRIER: Barrier notification
recommended for graph display with horizontal barrier lines, event Id: 16
Notifies of a barrier.
i f ( AYU event ) { AYU event (AYU BARRIER, 0 ,NULL ) ; }
AYU ADDWAITONTASK: Wait-on event
do not use, development in progress, event Id: 17
For treating wait-on events.
Do not use! This is under development!
3.2. Requests
tbd.
4. The callback functions
These functions are declared in the header file Ayudame.h as weak references. This way
it is possible to check whether an implementation of the functions exist during runtime.
This enables an application to run with or without the preloaded Ayudame library
without recompiling (see code example in sec. 2.2).
4.1. The AYU event callback function
tbd.
A. Sources
A.1. The header Ayudame.h
Steffen Brinkmann - HLRS, Universit¨at Stuttgart
12
A Sources
Listing 1: The main header of the Ayudame package
/∗ ∗∗∗H∗ AYUDAME/ Ayudame types . h
∗ NAME
∗
Ayudame types . h − h e a d e r f i l e f o r t h e e v e n t and r e q u e s t t y p e s o f t h e
∗
AYUDAME package
∗ DESCRIPTION
∗
This h e a d e r f i l e d e c l a r e s t h e f o l l o w i n g e l e m e n t s :
∗
∗ enum a y u e v e n t t
∗
∗ enum a y u r e q u e s t t
∗
∗ . . . TODO . . .
∗∗∗∗∗ ∗/
#i f n d e f AYUDAME H
#define AYUDAME H
#include <s t d i n t . h>
#include <u n i s t d . h>
//#d e f i n e
REENTRANT // d e f i n e d by d e f a u l t by g c c
#i f n d e f AYU VERBOSE
# define AYU VERBOSE 0
#endif
#i f n d e f AYU CONNECTTOSOCKET
# define AYU CONNECTTOSOCKET 1
#endif
#i f n d e f AYU WRITETOSTDOUT
# define AYU WRITETOSTDOUT 0
#endif
#i f n d e f AYU MASTER TASKID
# define AYU MASTER TASKID 0
#endif
#define AYU VERSION " 0.9.20121030 "
// i n c l u d e s and d e f i n e s f o r time measurement with r d t s c
#i f d e f i n e d ( l i n u x )
# include <e n d i a n . h>
#e l i f d e f i n e d ( F r e e B S D ) | | d e f i n e d ( NetBSD )
# include <s y s / e n d i a n . h>
#e l i f d e f i n e d ( OpenBSD )
# include <s y s / t y p e s . h>
// # d e f i n e b e 1 6 t o h ( x ) b e t o h 1 6 ( x )
// # d e f i n e b e 3 2 t o h ( x ) b e t o h 3 2 ( x )
# define b e 6 4 t o h ( x ) b e t o h 6 4 ( x )
#e l s e
# error ERROR: System not r e c o g n i s e d !
#endif
#i f n d e f h t o b e 6 4
# include <byteswap . h>
# i f BYTE ORDER == LITTLE ENDIAN
#
define h t o b e 6 4 ( x )
bswap 64 ( x )
#
define b e 6 4 t o h ( x )
bswap 64 ( x )
# else
#
define h t o b e 6 4 ( x ) ( x )
#
define b e 6 4 t o h ( x ) ( x )
# endif
#endif
Ayudame
A.1
The header Ayudame.h
13
/∗
∗ #i f n d e f h t o b e 6 4 ( x ) #d e f i n e h t o b e 6 4 ( x ) ( ( ( ( u i n t 6 4 t ) h t o n l ( x ) ) << 3 2 ) +
∗ h t o n l ( x >> 3 2 ) ) #d e f i n e b e 6 4 t o h ( x ) ( ( ( ( u i n t 6 4 t ) n t o h l ( x ) ) << 3 2 ) +
∗ n t o h l ( x >> 3 2 ) ) #e n d i f
∗/
// −−−
const s i z e t A Y U b u f s i z e =8;
// s i z e o f message b u f f e r
extern unsigned long AYU n threads ;
// c u r r e n t number o f t h r e a d s
extern unsigned long AYU max threads ;
// maximum number o f t h r e a d s
/∗ ∗∗∗ t ∗ Ayudame types . h/ a y u e v e n t t
∗ NAME
∗
a y u e v e n t t − enum o f e v e n t s
∗ DESCRIPTION
∗
ayu event t c o n s i s t s of the f o l l o w i n g events :
∗
∗ AYU EVENT NULL −− ” no e v e n t ” , used f o r i n i t i a l i s a t i o n e t c .
∗
∗ AYU PREINIT −− r a i s e d i n c s s p r e i n i t ( )
∗
∗ AYU INIT −− r a i s e d i n c s s i n i t ( )
∗
∗ AYU FINISH −− r a i s e d i n c s s f i n i s h ( )
∗
∗ AYU REGISTERFUNCTION −− r a i s e d i n c s s r e g i s t e r T a s k ( ) with t h e
∗
f u n c t i o n name a s t h i r d p a r a m e t e r
∗
∗ AYU ADDTASK −− r a i s e d i n c s s a d d T a s k ( ) a f t e r a t a s k has been
∗
g e n e r a t e d with t h e t a s k
∗
p o i n t e r as second parameter
∗
∗ AYU ADDHIDDENTASK −− r a i s e d i n HiddenWork : : addPendingHiddenTask ( )
∗
a f t e r a hi dd en t a s k has
∗
been g e n e r a t e d with t h e t a s k p o i n t e r a s s e c o n d p a r a m e t e r
∗
∗ AYU ADDWAITONTASK −− r a i s e d i n c s s w a i t O n ( ) t o s i g n a l t h a t a wa it on
∗
d i r e c t i v e has been e n c o u n t e r e d . Note t h a t t h e t a s k I d i s a l l w a y s ” 0 ” .
∗
This e v e n t i s f o l l o w e d by one o r more AYU ADDDEPENDENCY e v e n t s .
∗
∗ AYU ADDDEPENDENCY −− r a i s e d i n P a r a m e t e r C o n v e r s i o n : : c o n v e r t ( ) with
∗
t a s k p o i n t e r a s s e c o n d p a r a m e t e r and T r a c k a b l e O b j e c t ( c o n t a i n i n g
∗
i n f o r m a t i o n about t h e l a s t W r i t e r and t h e dependency a d d r e s s a s
∗
t h i r d parameter
∗
∗ AYU ADDTASKTOQUEUE −− r a i s e d i n TaskQueues : : addGlobalTask ( ) ,
∗
TaskQueues : : addRRToNode , TaskQueues : : addTask ,
∗
TaskQueues : : addTaskWithLocality , TaskQueues : : a d d A f f i n e T a s k
∗
∗ AYU PRESELECTTASK −− r a i s e d i n
∗
WorkerEngine : : TaskExecutor : : tryToRunTaskOrWait ( ) b e f o r e a t a s k
∗
i s assigned
∗
∗ AYU PRERUNTASK −− r a i s e d i n
∗
WorkerEngine : : TaskExecutor : : tryToRunTaskOrWait ( ) a f t e r a t a s k i s
∗
assigned
∗
∗ AYU RUNTASK −− r a i s e d i n
∗
WorkerEngine : : TaskExecutor : : tryToRunTaskOrWait ( ) j u s t b e f o r e a t a s k
∗
i s executed
∗
∗ AYU POSTRUNTASK −− r a i s e d i n
∗
WorkerEngine : : TaskExecutor : : tryToRunTaskOrWait ( ) a f t e r runTask ( )
∗
∗ AYU RUNTASKFAILED −− r a i s e d i n
∗
WorkerEngine : : TaskExecutor : : tryToRunTaskOrWait ( ) i f E x c e p t i o n
∗
i s r a i s e d by runTask ( )
∗
∗ AYU REMOVETASK −− r a i s e d i n
∗
TaskGraph : : removeNodeAndEnqueueFreeSuccessors ( ) and
∗
HiddenWork : : removePendingHiddenTask ( )
∗
∗ AYU WAITON −− r a i s e d i n c s s w a i t O n ( )
∗
∗ AYU BARRIER −− r a i s e d i n c s s b a r r i e r
∗
∗ SOURCE
∗/
Steffen Brinkmann - HLRS, Universit¨at Stuttgart
14
A Sources
enum a y u e v e n t t {
AYU EVENT NULL = 0 ,
AYU PREINIT = 1 ,
AYU INIT = 2 ,
AYU FINISH = 3 ,
AYU REGISTERFUNCTION = 4 ,
AYU ADDTASK = 5 ,
AYU ADDHIDDENTASK = 6 ,
AYU ADDDEPENDENCY = 7 ,
AYU ADDTASKTOQUEUE = 8 ,
AYU PRESELECTTASK = 9 ,
AYU PRERUNTASK = 1 0 ,
AYU RUNTASK = 1 1 ,
AYU POSTRUNTASK = 1 2 ,
AYU RUNTASKFAILED = 1 3 ,
AYU REMOVETASK = 1 4 ,
AYU WAITON = 1 5 ,
AYU BARRIER = 1 6 ,
AYU ADDWAITONTASK = 17
};
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ t ∗ Ayudame types . h/ a y u r e q u e s t t
∗ NAME
∗
a y u r e q u e s t t − enum o f r e q u e s t s
∗ DESCRIPTION
∗
ayu event t c o n s i s t s of the f o l l o w i n g events :
∗
∗ AYU REQUEST NULL −− ” no r e q u e s t ” , used f o r i n i t i a l i s a t i o n
∗
∗ AYU NOREQUEST −− e x p l i c i t ” no r e q u e s t ”
∗
∗ AYU PAUSEONEVENT −− pause r e q u e s t , e v e n t upon which t h e program s h o u l d
∗
pause i s g i v e n a s t h i r d parameter , f o u r t h p a r a m e t e r i s 0 f o r ” o f f ”
∗
( ” un−pause ” ) and 1 f o r ” on ”
∗
∗ AYU PAUSEONTASK −− pause r e q u e s t , t a s k i d i s g i v e n a s t h i r d parameter ,
∗
f o u r t h p a r a m e t e r i s 0 f o r ” o f f ” ( ” un−pause ” ) and 1 f o r ” on ”
∗
∗ AYU PAUSEONFUNCTION −− pause r e q u e s t , f u n c t i o n i d i s g i v e n a s t h i r d
∗
parameter , f o u r t h p a r a m e t e r i s 0 f o r ” o f f ” ( ” un−pause ” ) and 1 f o r ” on ”
∗
∗ AYU STEP −− run u n t i l n e x t pause c o n d i t i o n i s r e a c h e d
∗
∗ AYU BREAKPOINT −− s e t b r e a k p o i n t , i . e . don ’ t a s s i g n new t a s k s , t h i r d
∗
p a r a m e t e r i s 0 f o r ” o f f ” ( ” un−pause ” ) and 1 f o r ” on ”
∗ SOURCE
∗/
enum a y u r e q u e s t t {
AYU REQUEST NULL = 0 ,
AYU NOREQUEST = 1 ,
AYU PAUSEONEVENT = 2 ,
AYU PAUSEONTASK = 3 ,
AYU PAUSEONFUNCTION = 4 ,
AYU STEP = 5 ,
AYU BREAKPOINT = 6 ,
AYU BLOCKTASK = 7 ,
AYU PRIORITISETASK = 8 ,
AYU SETNUMTHREADS = 9
};
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ t ∗ Ayudame types . h/ a y u r u n t i m e t
∗ NAME
∗
a y u r u n t i m e t − enum o f r u n t i m e i d s
∗ DESCRIPTION
Ayudame
A.1
The header Ayudame.h
15
∗
ayu event t c o n s i s t s of the f o l l o w i n g i d s :
∗
∗ AYU RT UNKNOWN −− no o r unknown runtime , used f o r
∗
∗ AYU RT CPPSS −− CPPSS r u n t i m e
∗
∗ AYU RT SMPSS −− SmpSs r u n t i m e
∗
∗ AYU RT OMPSS −− OmpSs r u n t i m e
∗
∗ AYU RT GOMP −− GNU OpenMP r u n t i m e
∗
∗ AYU RT CILK −− CILK r u n t i m e
∗ SOURCE
∗/
enum a y u r u n t i m e t {
AYU RT UNKNOWN = 0 ,
AYU RT CPPSS = 1 ,
AYU RT SMPSS = 2 ,
AYU RT OMPSS = 3 ,
AYU RT GOMP = 4 ,
AYU RT CILK = 5
};
/∗ ∗∗∗∗ ∗/
initialisation
extern " C " {
/∗ ∗∗∗ f ∗ AYUDAME/AYU event
∗ NAME
∗
AYU event
∗
− c a l l b a c k f o r t h e ∗ Ss r u n t i m e
∗ SYNOPSIS
∗
AYU event ( event , t a s k I d , p o i n t e r )
∗ DESCRIPTION
∗
t h i s f u n c t i o n i s c a l l e d from t h e ∗ Ss r u n t i m e t o communicate
∗
with t h e AYUDAME package . Events o f t y p e a y u e v e n t t , t h e t a s k ID
∗
o f t h e c a l l i n g t a s k and a p o i n t e r t o a r b i t r a r y data can be s e n t .
∗
AYU event w i l l c o n n e c t t o a c l i e n t v i a t c p s o c k e t s and p a s s on
∗
the information .
∗ PARAMETERS
∗
ayu event t event
// t y p e o f e v e n t
∗
const int64 t taskId
// t a s k I d from which t h e e v e n t i s s e n t
∗
v o i d ∗p
// p o i n t e r t o f u r t h e r data
∗ RETURN VALUE
∗
void
∗ SOURCE
∗/
void AYU event ( a y u e v e n t t event , const i n t 6 4 t t a s k I d , void ∗p )
attribute
( ( weak ) ) ;
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ f ∗ AYUDAME/ AYU getBreakpoint
∗ NAME
∗
AYU getBreakpoint
∗
− r e t u r n AYU breakpoint
∗ SYNOPSIS
∗
b r e a k p o i n t = AYU getBreakpoint ( )
∗ DESCRIPTION
∗
Locks t h e g l o b a l v a r i a b l e AYU breakpoint , r e t u r n s i t s v a l u e
∗
and u n l o c k s i t
∗ PARAMETERS
∗
void
∗ RETURN VALUE
∗
1 i f AYU breakpoint i s s e t
∗
0 i f AYU breakpoint i s not s e t
∗ SOURCE
∗/
i n t AYU getBreakpoint ( void )
attribute
( ( weak ) ) ;
Steffen Brinkmann - HLRS, Universit¨at Stuttgart
16
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ f ∗ AYUDAME/ AYU isBlocked
∗ NAME
∗
AYU isBlocked
∗
− return true i f task i s blocked
∗ SYNOPSIS
∗
i f ( AYU isBlocked ( t a s k I d ) ) { d o s o m e t h i n g ( ) ; }
∗ DESCRIPTION
∗
Locks t h e g l o b a l v a r i a b l e AYU blockedTask u s i n g t h e
∗
b r e a k p o i n t mutex l o c k , compares t o i t
∗
t a s k I d g i v e n a s p a r a m e t e r and r e t u r n s r e s u l t
∗ PARAMETERS
∗
∗ const int taskId
∗ RETURN VALUE
∗
true i f task i s blocked
∗
f a l s e i f t a s k i s not b l o c k e d
∗ SOURCE
∗/
bool AYU isBlocked ( const i n t t a s k I d )
attribute
( ( weak ) ) ;
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ f ∗ AYUDAME/ A Y U g e t P r i o r i t y L e v e l
∗ NAME
∗
AYU getPriorityLevel
∗
− returns p r i o r i t y of task
∗ SYNOPSIS
∗
AYU getPriorityLevel ( taskId )
∗ DESCRIPTION
∗
r e t u r n s t h e p r i o r i t y o f a t a s k i d e n t i f i e d by i t s i d .
∗
I f t h e p r i o r i t y has not been changed i n Ayudame i t
∗
r e t u r n s −1.
∗ PARAMETERS
∗
int taskId
∗ RETURN VALUE
∗
−1: i f p r i o r i t y has not changed
∗
0:
low ( no ) p r i o r i t y
∗
positive integer : priority level
∗ SOURCE
∗/
int AYU getPriorityLevel ( int taskId )
attribute
( ( weak ) ) ;
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ f ∗ AYUDAME/AYU getNumThreads
∗ NAME
∗
AYU getNumThreads
∗
− r e t u r n s number o f t h r e a d s s e t by AYUDAME
∗ SYNOPSIS
∗
runtime setNumThreads ( AYU getNumThreads ( ) ) ;
∗ DESCRIPTION
∗
r e t u r n s t h e number o f t h r e a d s a s s e t by ayudame
∗ PARAMETERS
∗
void
∗ RETURN VALUE
∗
u n s i g n e d i n t : number o f t h r e a d s
∗ SOURCE
∗/
unsigned i n t AYU getNumThreads ( )
attribute
( ( weak ) ) ;
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ f ∗ AYUDAME/AYU setNumThreads
∗ NAME
Ayudame
A Sources
A.1
The header Ayudame.h
17
∗
AYU setNumThreads
∗
− s e t s number o f t h r e a d s i n t h e r u n t i m e
∗ SYNOPSIS
∗
AYU setNumThreads ( n t h r e a d s ) ;
∗ DESCRIPTION
∗
This c a l l b a c k f u n c t i o n can be implemented i n t h e S t a r S s
∗
r u n t i m e . I f i t i s not implemented , t h e c l i e n t o f t h e
∗
AYUDAME l i b r a r y w i l l not be a b l e t o change t h e number o f
∗
threads .
∗ PARAMETERS
∗
unsigned i n t n threads
∗ RETURN VALUE
∗
void
∗/
void AYU setNumThreads ( unsigned i n t n t h r e a d s )
attribute
( ( weak ) ) ;
/∗ ∗∗∗∗ ∗/
/∗ ∗∗∗ f ∗ AYUDAME/ A Y U r e g i s t e r T a s k
∗ NAME
∗
AYU registerTask
∗
− o b s o l e t e . k e p t f o r backward c o m p a t i b i l i t y
∗ SYNOPSIS
∗
∗ DESCRIPTION
∗
∗ PARAMETERS
∗
∗ RETURN VALUE
∗
∗ SOURCE
∗/
void A Y U r e g i s t e r T a s k ( void ∗ )
attribute
( ( weak ) ) ;
/∗ ∗∗∗∗ ∗/
}
#i f n d e f AYU MASTER TASKID
#define AYU MASTER TASKID 0
#endif
#endif //AYUDAME H
Steffen Brinkmann - HLRS, Universit¨at Stuttgart