ovs-vsctl: Try connecting only once for active connections by default.
[sliver-openvswitch.git] / lib / stream-provider.h
1 /*
2  * Copyright (c) 2009, 2010, 2012 Nicira, Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at:
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 #ifndef STREAM_PROVIDER_H
18 #define STREAM_PROVIDER_H 1
19
20 #include <sys/types.h>
21 #include "stream.h"
22
23 /* Active stream connection. */
24
25 /* Active stream connection.
26  *
27  * This structure should be treated as opaque by implementation. */
28 struct stream {
29     const struct stream_class *class;
30     int state;
31     int error;
32     ovs_be32 remote_ip;
33     ovs_be16 remote_port;
34     ovs_be32 local_ip;
35     ovs_be16 local_port;
36     char *name;
37 };
38
39 void stream_init(struct stream *, const struct stream_class *,
40                  int connect_status, const char *name);
41 void stream_set_remote_ip(struct stream *, ovs_be32 remote_ip);
42 void stream_set_remote_port(struct stream *, ovs_be16 remote_port);
43 void stream_set_local_ip(struct stream *, ovs_be32 local_ip);
44 void stream_set_local_port(struct stream *, ovs_be16 local_port);
45 static inline void stream_assert_class(const struct stream *stream,
46                                        const struct stream_class *class)
47 {
48     ovs_assert(stream->class == class);
49 }
50
51 struct stream_class {
52     /* Prefix for connection names, e.g. "tcp", "ssl", "unix". */
53     const char *name;
54
55     /* True if this stream needs periodic probes to verify connectivity.  For
56      * streams which need probes, it can take a long time to notice the
57      * connection was dropped. */
58     bool needs_probes;
59
60     /* Attempts to connect to a peer.  'name' is the full connection name
61      * provided by the user, e.g. "tcp:1.2.3.4".  This name is useful for error
62      * messages but must not be modified.
63      *
64      * 'suffix' is a copy of 'name' following the colon and may be modified.
65      * 'dscp' is the DSCP value that the new connection should use in the IP
66      * packets it sends.
67      *
68      * Returns 0 if successful, otherwise a positive errno value.  If
69      * successful, stores a pointer to the new connection in '*streamp'.
70      *
71      * The open function must not block waiting for a connection to complete.
72      * If the connection cannot be completed immediately, it should return
73      * EAGAIN (not EINPROGRESS, as returned by the connect system call) and
74      * continue the connection in the background. */
75     int (*open)(const char *name, char *suffix, struct stream **streamp,
76                 uint8_t dscp);
77
78     /* Closes 'stream' and frees associated memory. */
79     void (*close)(struct stream *stream);
80
81     /* Tries to complete the connection on 'stream'.  If 'stream''s connection
82      * is complete, returns 0 if the connection was successful or a positive
83      * errno value if it failed.  If the connection is still in progress,
84      * returns EAGAIN.
85      *
86      * The connect function must not block waiting for the connection to
87      * complete; instead, it should return EAGAIN immediately. */
88     int (*connect)(struct stream *stream);
89
90     /* Tries to receive up to 'n' bytes from 'stream' into 'buffer', and
91      * returns:
92      *
93      *     - If successful, the number of bytes received (between 1 and 'n').
94      *
95      *     - On error, a negative errno value.
96      *
97      *     - 0, if the connection has been closed in the normal fashion.
98      *
99      * The recv function will not be passed a zero 'n'.
100      *
101      * The recv function must not block waiting for data to arrive.  If no data
102      * have been received, it should return -EAGAIN immediately. */
103     ssize_t (*recv)(struct stream *stream, void *buffer, size_t n);
104
105     /* Tries to send up to 'n' bytes of 'buffer' on 'stream', and returns:
106      *
107      *     - If successful, the number of bytes sent (between 1 and 'n').
108      *
109      *     - On error, a negative errno value.
110      *
111      *     - Never returns 0.
112      *
113      * The send function will not be passed a zero 'n'.
114      *
115      * The send function must not block.  If no bytes can be immediately
116      * accepted for transmission, it should return -EAGAIN immediately. */
117     ssize_t (*send)(struct stream *stream, const void *buffer, size_t n);
118
119     /* Allows 'stream' to perform maintenance activities, such as flushing
120      * output buffers.
121      *
122      * May be null if 'stream' doesn't have anything to do here. */
123     void (*run)(struct stream *stream);
124
125     /* Arranges for the poll loop to wake up when 'stream' needs to perform
126      * maintenance activities.
127      *
128      * May be null if 'stream' doesn't have anything to do here. */
129     void (*run_wait)(struct stream *stream);
130
131     /* Arranges for the poll loop to wake up when 'stream' is ready to take an
132      * action of the given 'type'. */
133     void (*wait)(struct stream *stream, enum stream_wait_type type);
134 };
135 \f
136 /* Passive listener for incoming stream connections.
137  *
138  * This structure should be treated as opaque by stream implementations. */
139 struct pstream {
140     const struct pstream_class *class;
141     char *name;
142 };
143
144 void pstream_init(struct pstream *, const struct pstream_class *, const char *name);
145 static inline void pstream_assert_class(const struct pstream *pstream,
146                                         const struct pstream_class *class)
147 {
148     ovs_assert(pstream->class == class);
149 }
150
151 struct pstream_class {
152     /* Prefix for connection names, e.g. "ptcp", "pssl", "punix". */
153     const char *name;
154
155     /* True if this pstream needs periodic probes to verify connectivity.  For
156      * pstreams which need probes, it can take a long time to notice the
157      * connection was dropped. */
158     bool needs_probes;
159
160     /* Attempts to start listening for stream connections.  'name' is the full
161      * connection name provided by the user, e.g. "ptcp:1234".  This name is
162      * useful for error messages but must not be modified.
163      *
164      * 'suffix' is a copy of 'name' following the colon and may be modified.
165      * 'dscp' is the DSCP value that the new connection should use in the IP
166      * packets it sends.
167      *
168      * Returns 0 if successful, otherwise a positive errno value.  If
169      * successful, stores a pointer to the new connection in '*pstreamp'.
170      *
171      * The listen function must not block.  If the connection cannot be
172      * completed immediately, it should return EAGAIN (not EINPROGRESS, as
173      * returned by the connect system call) and continue the connection in the
174      * background. */
175     int (*listen)(const char *name, char *suffix, struct pstream **pstreamp,
176                   uint8_t dscp);
177
178     /* Closes 'pstream' and frees associated memory. */
179     void (*close)(struct pstream *pstream);
180
181     /* Tries to accept a new connection on 'pstream'.  If successful, stores
182      * the new connection in '*new_streamp' and returns 0.  Otherwise, returns
183      * a positive errno value.
184      *
185      * The accept function must not block waiting for a connection.  If no
186      * connection is ready to be accepted, it should return EAGAIN. */
187     int (*accept)(struct pstream *pstream, struct stream **new_streamp);
188
189     /* Arranges for the poll loop to wake up when a connection is ready to be
190      * accepted on 'pstream'. */
191     void (*wait)(struct pstream *pstream);
192
193     /* Set DSCP value of the listening socket. */
194     int (*set_dscp)(struct pstream *pstream, uint8_t dscp);
195 };
196
197 /* Active and passive stream classes. */
198 extern const struct stream_class tcp_stream_class;
199 extern const struct pstream_class ptcp_pstream_class;
200 extern const struct stream_class unix_stream_class;
201 extern const struct pstream_class punix_pstream_class;
202 #ifdef HAVE_OPENSSL
203 extern const struct stream_class ssl_stream_class;
204 extern const struct pstream_class pssl_pstream_class;
205 #endif
206
207 #endif /* stream-provider.h */