NAME

       TAU_REGISTER_CONTEXT_EVENT - Registers a context event

SYNOPSIS

       C/C++:

       TAU_REGISTER_CONTEXT_EVENT(TauUserEvent variable, char *event_name);

       Fortran:

       TAU_REGISTER_CONTEXT_EVENT(int variable(2), character event_name(size));

DESCRIPTION

       Creates a context event with name. A context event appends the names of routines executing
       on the callstack to the name specified by the user. Whenver a context event is triggered,
       the callstack is examined to determine the context of execution. Starting from the parent
       function where the event is triggered, TAU walks up the callstack to a depth specified by
       the user in the environment variable TAU_CALLPATH_DEPTH. If this environment variable is
       not specified, TAU uses 2 as the default depth. For e.g., if the user registers a context
       event with the name "memory used" and specifies 3 as the callpath depth, and if the event
       is triggered in two locations (in routine a, when it was called by b, when it was called
       by c, and in routine h, when it was called by g, when it was called by i), then, we'd see
       the user defined event information for "memory used: c() => b() => a()" and "memory used:
       i() => g() => h()".

EXAMPLE

       C/C++ :

       int f2(void)
       {
         static int count = 0;
         count ++;
         TAU_PROFILE("f2()", "(sleeps 2 sec, calls f3)", TAU_USER);
         TAU_REGISTER_CONTEXT_EVENT(event, "Iteration count");
       /*
         if (count == 2)
           TAU_DISABLE_CONTEXT_EVENT(event);
       */
         printf("Inside f2: sleeps 2 sec, calls f3\n");

         TAU_CONTEXT_EVENT(event, 232+count);
         sleep(2);
         f3();
         return 0;
       }

       Fortran :

       subroutine foo(id)
         integer id

         integer profiler(2) / 0, 0 /
         integer maev(2) / 0, 0 /
         integer mdev(2) / 0, 0 /
         save profiler, maev, mdev

         integer :: ierr
         integer :: h, t, u
         INTEGER, ALLOCATABLE :: STORAGEARY(:)
         DOUBLEPRECISION   edata

         call TAU_PROFILE_TIMER(profiler, 'FOO')
         call TAU_PROFILE_START(profiler)
         call TAU_PROFILE_SET_NODE(0)

         call TAU_REGISTER_CONTEXT_EVENT(maev, "STORAGEARY Alloc [cubes.f:20]")
         call TAU_REGISTER_CONTEXT_EVENT(mdev, "STORAGEARY Dealloc [cubes.f:37]")

         allocate(STORAGEARY(1:999), STAT=IERR)
         edata = SIZE(STORAGEARY)*sizeof(INTEGER)
         call TAU_CONTEXT_EVENT(maev, edata)
         ...
         deallocate(STORAGEARY)
         edata = SIZE(STORAGEARY)*sizeof(INTEGER)
         call TAU_CONTEXT_EVENT(mdev, edata)
         call TAU_PROFILE_STOP(profiler)
         end subroutine foo

SEE ALSO

       TAU_CONTEXT_EVENT(3), TAU_ENABLE_CONTEXT_EVENT(3), TAU_DISABLE_CONTEXT_EVENT(3),
       TAU_REGISTER_EVENT(3), TAU_REPORT_STATISTICS(3), TAU_REPORT_THREAD_STATISTICS(3),
       TAU_GET_EVENT_NAMES(3), TAU_GET_EVENT_VALS(3)

                                            08/31/2005                    TAU_REGISTER_CONTEXT(3)