Download AYUDAME User Manual
Transcript
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