← Back to branch summary

~oif-team/geis/trunk

« back to all changes in this revision

Viewing changes to libutouch-geis/geis_backend_multiplexor.h

  • Committer: Stephen M. Webb
  • Date: 2010-12-06 12:10:40 UTC
  • mfrom: (87.1.25 geis2)
  • Revision ID: stephen.webb@canonical.com-20101206121040-y9dnfcl89kdot63t
Added a back end base and test fixture.

Show diffs side-by-side

added added

removed removed

Lines of Context:
libutouch-geis/geis_backend_multiplexor.h
 
1
/**
 
2
 * @file geis_backend_multiplexor.h
 
3
 * @brief internal GEIS backend multiplexor interface
 
4
 *
 
5
 * Copyright 2010 Canonical Ltd.
 
6
 *
 
7
 * This library is free software; you can redistribute it and/or modify it under
 
8
 * the terms of the GNU Lesser General Public License as published by the Free
 
9
 * Software Foundation; either version 3 of the License, or (at your option) any
 
10
 * later version.
 
11
 *
 
12
 * This library is distributed in the hope that it will be useful, but WITHOUT
 
13
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 
14
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 
15
 * details.
 
16
 *
 
17
 * You should have received a copy of the GNU Lesser General Public License
 
18
 * along with this program; if not, write to the Free Software Foundation, Inc.,
 
19
 * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 
20
 */
 
21
#ifndef GEIS_BACKEND_MULTIPLEXOR_H_
 
22
#define GEIS_BACKEND_MULTIPLEXOR_H_
 
23
 
 
24
#include "geis/geis.h"
 
25
 
 
26
 
 
27
/**
 
28
 * Multiplexes back end events into a single notification file descriptor.
 
29
 *
 
30
 * The GEIS API presents a single file descriptor to the application to watch
 
31
 * for activity notification.  A back end may be monitoring activity on more
 
32
 * than one file descriptor.  The multiplexor combines these requirements.
 
33
 */
 
34
typedef struct _GeisBackendMultiplexor *GeisBackendMultiplexor;
 
35
 
 
36
/**
 
37
 * Indicates the type of fd event that occurred on a multiplexed descriptor.
 
38
 */
 
39
typedef enum _GeisBackendMultiplexorEvent
 
40
{
 
41
  GEIS_BE_MX_READ_AVAILABLE,
 
42
  GEIS_BE_MX_WRITE_AVAILABLE
 
43
} GeisBackendMultiplexorEvent;
 
44
 
 
45
/**
 
46
 * Handles events occurring on multiplexed file descriptors.
 
47
 *
 
48
 * Back ends must provide a callback with this signature to the multiplexor.
 
49
 */
 
50
typedef void (*GeisBackendFdEventCallback)(int                          fd,
 
51
                                           GeisBackendMultiplexorEvent  event,
 
52
                                           void                        *context);
 
53
 
 
54
/**
 
55
 * Constructs a new back end multiplexor.
 
56
 */
 
57
GeisBackendMultiplexor geis_backend_multiplexor_new();
 
58
 
 
59
/**
 
60
 * A reasonable default value for the max_events_per_pump parameter to
 
61
 * geis_backend_multiplexor_new().
 
62
 */
 
63
#define GEIS_BE_MX_DEFAULT_EVENTS_PER_PUMP  16
 
64
 
 
65
/**
 
66
 * Destroys a back end multiplexor.
 
67
 *
 
68
 * @param[in] mx  The back end multiplexor to destroy.
 
69
 */
 
70
void geis_backend_multiplexor_delete(GeisBackendMultiplexor mx);
 
71
 
 
72
/**
 
73
 * Adds a file descriptor to a back end multiplexor.
 
74
 *
 
75
 * @param[in] mx  The back end multiplexor.
 
76
 * @param[in] fd  The file descriptor to add.
 
77
 */
 
78
void geis_backend_multiplexor_add_fd(GeisBackendMultiplexor      mx,
 
79
                                     int                         fd,
 
80
                                     GeisBackendFdEventCallback  callback,
 
81
                                     void                       *context);
 
82
 
 
83
/**
 
84
 * Removes a file descriptor from a back end multiplexor.
 
85
 *
 
86
 * @param[in] mx  The back end multiplexor.
 
87
 * @param[in] fd  The file descriptor to remove.
 
88
 */
 
89
void geis_backend_multiplexor_remove_fd(GeisBackendMultiplexor mx,
 
90
                                        int                    fd);
 
91
 
 
92
/**
 
93
 * Gets the file descriptor of the back end multiplexor.
 
94
 *
 
95
 * @param[in] mx  The back end multiplexor.
 
96
 */
 
97
int geis_backend_multiplexor_fd(GeisBackendMultiplexor mx);
 
98
 
 
99
/**
 
100
 * Gets the maximum number of fd events per pump.
 
101
 *
 
102
 * @param[in] mx                   The back end multiplexor.
 
103
 */
 
104
int geis_backend_multiplexor_max_events_per_pump(GeisBackendMultiplexor mx);
 
105
 
 
106
/**
 
107
 * Sets the maximum fd events per pump of the multiplexor.
 
108
 *
 
109
 * @param[in] mx                   The back end multiplexor.
 
110
 * @param[in] max_events_per_pump  The maximum number of fd events pumped
 
111
 *                                 per call of geis_backend_multiplexor_pump().
 
112
 *
 
113
 * This value is tunable to accommodate different back ends and
 
114
 * application/toolkit requirements.
 
115
 */
 
116
void geis_backend_multiplexor_set_max_events_per_pump(GeisBackendMultiplexor mx,
 
117
                                                      int max_events_per_pump);
 
118
 
 
119
/**
 
120
 * Exercises the back end multiplexor.
 
121
 *
 
122
 * @param[in] mx  The back end multiplexor.
 
123
 *
 
124
 * Dispatches any events on multiplexed file descriptors to their assciated
 
125
 * handlers.
 
126
 */
 
127
GeisStatus geis_backend_multiplexor_pump(GeisBackendMultiplexor mx);
 
128
 
 
129
#endif /* GEIS_BACKEND_MULTIPLEXOR_H_ */