Statistics
| Branch: | Revision:

napa-baselibs / include / napa.h @ 507372bb

History | View | Annotate | Download (4.26 KB)

1
#ifndef _NAPA_H
2
#define _NAPA_H
3

    
4
/** @mainpage
5

6
   @section intro Introduction
7

8
   The NAPA prototype code is the reference implementation for the evolving WineStreamer (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 NAPA 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 some of the NAPA libraries.
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 napa.h
50
 *
51
 * Common definitions for the NAPA framework reference implementation, to be included by all 
52
 * applications using these libraries.
53
 *
54
 * This header file contains basic, system-wide definitions (such as PeerID) which are necessary
55
 * for different 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
#ifdef WIN32
66
#include <winsock2.h>
67
#endif
68

    
69
#ifndef byte
70
/** 8-bit unsigned type */
71
typedef u_char byte;
72
#endif
73

    
74
/** General-purpose opaque handle type */
75
typedef void *HANDLE;
76

    
77
/** Opaque network-wide PeerID */
78
typedef char PeerID[64];
79

    
80
/** eventbase pointer for the libevent2 framework */
81
extern struct event_base *eventbase;
82

    
83
#ifdef __cplusplus
84
extern "C" {
85
#endif
86

    
87
/** Function to initialize the framework.
88
 *
89
 * This function has to be called first, before any other NAPA-BASELIBS-provided function.
90
 
91
   @param event2_base libevent2 base structure, provided by the external application
92
*/
93
void napaInit(void *event2_base);
94

    
95
/** Function to yield control (sleep) 
96
*/
97
void napaYield();
98

    
99
/**
100
  Register a function to be called periodically.
101

102
  Use this function for scheduling periodic activity. 
103
  The callback function supports one extra argument besides its own handle.
104

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

    
114
/**
115
  Stop periodically calling the callback registered to the handle.
116

117
  @param h handle to the callback.
118
  @see napaStartPeriodic
119
*/
120
void napaStopPeriodic(HANDLE h);
121

    
122

    
123
/** Convenience function to print a timeval */
124
const char *timeval2str(const struct timeval *ts);
125

    
126
#ifdef __cplusplus
127
}
128
#endif
129

    
130
#endif