ovsdb-client: Improve manpage.
[openvswitch] / ovsdb / server.h
1 /* Copyright (c) 2011 Nicira Networks
2  *
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at:
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15
16 #ifndef SERVER_H
17 #define SERVER_H 1
18
19 #include "hmap.h"
20 #include "list.h"
21
22 /* Abstract representation of an OVSDB client connection, not tied to any
23  * particular network protocol.  Protocol implementations
24  * (e.g. jsonrpc-server.c) embed this in a larger data structure.  */
25 struct ovsdb_session {
26     struct ovsdb *db;
27     struct list completions;    /* Completed triggers. */
28     struct hmap waiters;        /* "ovsdb_lock_waiter *"s by lock name. */
29 };
30
31 void ovsdb_session_init(struct ovsdb_session *, struct ovsdb *);
32 void ovsdb_session_destroy(struct ovsdb_session *);
33
34 struct ovsdb_lock_waiter *ovsdb_session_get_lock_waiter(
35     const struct ovsdb_session *, const char *lock_name);
36
37 /* A database lock.
38  *
39  * A lock always has one or more "lock waiters" kept on a list.  The waiter at
40  * the head of the list owns the lock. */
41 struct ovsdb_lock {
42     struct ovsdb_server *server; /* The containing server. */
43     char *name;                  /* Unique name. */
44     struct hmap_node hmap_node;  /* In ovsdb_server's "locks" hmap. */
45     struct list waiters;         /* Contains "struct ovsdb_lock_waiter"s. */
46 };
47
48 struct ovsdb_lock_waiter *ovsdb_lock_get_owner(const struct ovsdb_lock *);
49
50 /* How to obtain a lock. */
51 enum ovsdb_lock_mode {
52     OVSDB_LOCK_WAIT,            /* By waiting for it to become available. */
53     OVSDB_LOCK_STEAL            /* By stealing it from the owner. */
54 };
55
56 /* A session's request for a database lock. */
57 struct ovsdb_lock_waiter {
58     enum ovsdb_lock_mode mode;
59     char *lock_name;
60
61     struct ovsdb_lock *lock;    /* The lock being waited for. */
62     struct list lock_node;      /* In ->lock->waiters's list. */
63
64     struct ovsdb_session *session;
65     struct hmap_node session_node; /* In ->session->locks's hmap. */
66 };
67
68 struct ovsdb_session *ovsdb_lock_waiter_remove(struct ovsdb_lock_waiter *);
69 void ovsdb_lock_waiter_destroy(struct ovsdb_lock_waiter *);
70 bool ovsdb_lock_waiter_is_owner(const struct ovsdb_lock_waiter *);
71
72 /* Abstract representation of an OVSDB server not tied to any particular
73  * network protocol.  Protocol implementations (e.g. jsonrpc-server.c) embed
74  * this in a larger data structure.  */
75 struct ovsdb_server {
76     struct ovsdb *db;
77     struct hmap locks;     /* Contains "struct ovsdb_lock"s indexed by name. */
78 };
79
80 void ovsdb_server_init(struct ovsdb_server *, struct ovsdb *);
81 void ovsdb_server_destroy(struct ovsdb_server *);
82
83 struct ovsdb_lock_waiter *ovsdb_server_lock(struct ovsdb_server *,
84                                             struct ovsdb_session *,
85                                             const char *lock_name,
86                                             enum ovsdb_lock_mode,
87                                             struct ovsdb_session **victimp);
88
89 #endif /* ovsdb/server.h */