1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
/**
* mds — A micro-display server
* Copyright © 2014, 2015 Mattias Andrée (maandree@member.fsf.org)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef MDS_LIBMDSCLIENT_COMM_H
#define MDS_LIBMDSCLIENT_COMM_H
#include <stdint.h>
#include <stddef.h>
#include <pthread.h>
#include <time.h>
#include <errno.h>
#include <inttypes.h>
/**
* A connection to the display server
*/
typedef struct libmds_connection
{
/**
* The file descriptor of the socket
* connected to the display server,
* -1 if not connected
*/
int socket_fd;
/**
* The ID of the _previous_ message
*/
uint32_t message_id;
/**
* The client ID, `NULL` if anonymous
*/
char* client_id;
/**
* Mutex used to hinder concurrent modification
* and concurrent message passing
*
* This mutex is a fast mutex, a thread may not
* lock it more than once
*/
pthread_mutex_t mutex;
/**
* Whether `mutex` is initialised
*/
int mutex_initialised;
} libmds_connection_t;
/**
* Initialise a connection descriptor
*
* @param this The connection descriptor
* @return Zero on success, -1 on error, `ernno`
* will have been set accordingly on error
*/
__attribute__((nonnull))
int libmds_connection_initialise(libmds_connection_t* restrict this);
/**
* Allocate and initialise a connection descriptor
*
* @return The connection descriptor, `NULL` on error,
* `errno` will have been set accordingly on error
*
* @throws ENOMEM Out of memory, Possibly, the process hit the RLIMIT_AS or
* RLIMIT_DATA limit described in getrlimit(2).
*/
libmds_connection_t* libmds_connection_create(void);
/**
* Release all resources held by a connection descriptor
*
* @param this The connection descriptor, may be `NULL`
*/
void libmds_connection_destroy(libmds_connection_t* restrict this);
/**
* Release all resources held by a connection descriptor,
* and release the allocation of the connection descriptor
*
* @param this The connection descriptor, may be `NULL`
*/
void libmds_connection_free(libmds_connection_t* restrict this);
/**
* TODO doc
*/
__attribute__((nonnull))
int libmds_connection_send(libmds_connection_t* restrict this, const char* message, size_t length);
/**
* TODO doc
*/
__attribute__((nonnull))
int libmds_connection_send_unlocked(libmds_connection_t* restrict this, const char* message, size_t length);
/**
* Lock the connection descriptor for being modified,
* or used to send data to the display, by another thread
*
* @param this:libmds_connection_t* The connection descriptor, must not be `NULL`
* @return :int Zero on success, -1 on error, `errno`
* will have been set accordingly on error
* @throws See pthread_mutex_lock(3)
*/
#define libmds_connection_lock(this) \
(errno = pthread_mutex_lock(&((this)->mutex)), (errno ? 0 : -1))
/**
* Lock the connection descriptor for being modified,
* or used to send data to the display, by another thread
*
* @param this:libmds_connection_t* The connection descriptor, must not be `NULL`
* @return :int Zero on success, -1 on error, `errno`
* will have been set accordingly on error
* @throws See pthread_mutex_trylock(3)
*/
#define libmds_connection_trylock(this) \
(errno = pthread_mutex_trylock(&((this)->mutex)), (errno ? 0 : -1))
/**
* Lock the connection descriptor for being modified,
* or used to send data to the display, by another thread
*
* @param this:libmds_connection_t* The connection descriptor, must not be `NULL`
* @param deadline:const struct timespec *restrict The absolute `CLOCK_REALTIME` time when the
* function shall fail, must not be `NULL`
* @return :int Zero on success, -1 on error, `errno`
* will have been set accordingly on error
* @throws See pthread_mutex_timedlock(3)
*/
#define libmds_connection_timedlock(this, deadline) \
(errno = pthread_mutex_timedlock(&((this)->mutex), deadline), (errno ? 0 : -1))
/**
* Undo the action of `libmds_connection_lock`, `libmds_connection_trylock`
* or `libmds_connection_timedlock`
*
* @param this:libmds_connection_t* The connection descriptor, must not be `NULL`
* @return :int Zero on success, -1 on error, `errno`
* will have been set accordingly on error
* @throws See pthread_mutex_unlock(3)
*/
#define libmds_connection_unlock(this) \
(errno = pthread_mutex_unlock(&((this)->mutex)), (errno ? 0 : -1))
/**
* Arguments for `libmds_compose` to compose the `Client ID`-header
*
* @param this: libmds_connection_t* The connection descriptor, must not be `NULL`
*/
#define LIBMDS_HEADER_CLIENT_ID(this) \
"?Client ID: %s", (this)->client_id != NULL, (this)->client_id
/**
* Arguments for `libmds_compose` to compose the `Message ID`-header
*
* @param this: libmds_connection_t* The connection descriptor, must not be `NULL`
*/
#define LIBMDS_HEADER_MESSAGE_ID(this) \
"Message ID: %"PRIu32, (this)->message_id
/**
* Arguments for `libmds_compose` to compose the standard headers:
* `Client ID` and `Message ID`
*
* @param this: libmds_connection_t* The connection descriptor, must not be `NULL`
*/
#define LIBMDS_HEADERS_STANDARD(this) \
LIBMDS_HEADER_CLIENT_ID(this), LIBMDS_HEADER_MESSAGE_ID(this)
#endif
|
