Statistics
| Branch: | Revision:

napa-baselibs / include / grapes.h @ 5f3adef4

History | View | Annotate | Download (4.21 KB)

1
#ifndef _GRAPES_H
2
#define _GRAPES_H
3

    
4
/** @mainpage
5

6
   @section intro Introduction
7

8
   The GRAPES prototype code is the reference implementation for the evolving GRAPES (aka. PULSE+) API.
9
   The main point is to demonstrate the intended final <b>structure</b> of the implementation, with
10
   omitting as much details as possible. Thus, the pre-prototype contains C language bindings for
11
   most of the datatypes, API calls etc. without the actual implementation, or with a <i>stub</i>
12
   implementation only for internal testing and to demonstrate the intended structure.
13

14
   Thus, most of the information found in this documentation is intended for GRAPES developers.
15

16
   @section structure Code Structure
17

18
   Each module (listed below) is separated into a sub-directory within the source tree.
19
   The public interfaces (APIs) are located in the <i>include/</i> sub-directory in the 
20
   correspondingly named .h file (e.g. ml.h for the Messaging Layer which resides in sub-directory <i>ml/</i>
21
   Module subdirectories are as follows:
22
        - ml/ - <b>Messaging Layer</b> - ml.h
23
        - mon/ - <b>Monitoring Layer</b> - mon.h
24
        - rep/ - <b>Repository</b> - repoclient.h
25
        - som/ - <b>Scheduler and Overlay Manager</b> - som.h
26
        - ul/ - <b>User</b> (interface) <b>Layer</b> - ul.h
27

28
   @section deps Dependencies
29

30
   The pre-prototype code uses a number of external open-source libraries.
31
   Most importantly, the <A HREF="http://monkey.org/~provos/libevent/">libevent</A> framework 
32
   is used to implement the reactive architecture, which was chosen as the 
33
   model of computation for GRAPES.
34
   Additionally, further open-source libraries are used to perform common tasks
35
   such as config file parsing and logging.
36
   
37
   Included libraries are:
38
        - <A HREF="http://monkey.org/~provos/libevent/">libevent</A>: event loop library to implement 
39
        the reactive architecture
40
        - <A HREF="http://www.nongnu.org/confuse/">libconfuse</A>: configuration file parsing library
41
        - <A HREF="http://sourceforge.net/projects/dclog/">dclog</A>: log message writer library
42

43
   @section copyright Copyright and related issues
44

45
   This code is has been released to the public.
46
*/
47

    
48

    
49
/** @file grapes.h
50
 *
51
 * Common definitions for the GRAPES framework reference implementation, to be included by all 
52
 * applications using GRAPES.
53
 *
54
 * This header file contains basic, system-wide definitions (such as PeerID) which are necessary
55
 * for different GRAPES modules to interact.
56
 * 
57
 * Libraries and system-wide dependencies are included from this file, for example standard C
58
 * header files for common types (e.g. <i>bool</i> or <i>byte<i>
59
 *
60
 */
61

    
62
#include <sys/types.h>
63
#include <stdbool.h>
64
#include <stdlib.h>
65

    
66
#ifndef byte
67
/** 8-bit unsigned type */
68
typedef u_char byte;
69
#endif
70

    
71
/** General-purpose opaque handle type */
72
typedef void *HANDLE;
73

    
74
/** Opaque network-wide PeerID */
75
typedef char PeerID[64];
76

    
77
/** eventbase pointer for the libevent2 framework */
78
extern struct event_base *eventbase;
79

    
80
#ifdef __cplusplus
81
extern "C" {
82
#endif
83

    
84
/** Function to initialize the GRAPES framework.
85
 *
86
 * This function has to be called first, before any other GRAPES-provided function.
87
 
88
   @param event2_base libevent2 base structure, provided by the external application
89
*/
90
void grapesInit(void *event2_base);
91

    
92
/** Function to yield control (sleep) 
93
*/
94
void grapesYield();
95

    
96
/**
97
  Register a function to be called periodically.
98

99
  Use this function for scheduling periodic activity. 
100
  The callback function supports one extra argument besides its own handle.
101

102
  @param[in] start time of first exection, in timeval units from now. NULL (or timeval {0,0}) means "now" or "asap". 
103
  @param[in] frequency invocation frequency .
104
  @param[in] cb callback function to be called periodically.
105
  @param[in] cbarg argument for the callback function.
106
  @return handle to the function or NULL on error.
107
  @see grapesStopPeriodic
108
*/
109
HANDLE grapesSchedulePeriodic(const struct timeval *start, double frequency, void(*cb)(HANDLE handle, void *arg), void *cbarg);
110

    
111
/**
112
  Stop periodically calling the callback registered to the handle.
113

114
  @param h handle to the callback.
115
  @see grapesStartPeriodic
116
*/
117
void grapesStopPeriodic(HANDLE h);
118

    
119

    
120
/** Convenience function to print a timeval */
121
const char *timeval2str(const struct timeval *ts);
122

    
123
#ifdef __cplusplus
124
}
125
#endif
126

    
127
#endif