aboutsummaryrefslogtreecommitdiffstats
path: root/bus.py
blob: 7025dd8f39cba89ce4eb1835bfa81dd4e6c2e6e4 (plain) (blame)
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
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
# -*- python -*-
# See LICENSE file for copyright and license details.


class Bus:
    '''
    Message broadcasting interprocess communication
    '''
    
    
    RDONLY = 1
    '''
    Open the bus for reading only
    '''

    WRONLY = 0
    '''
    Open the bus for writing only
    '''
    
    RDWR = 0
    '''
    Open the bus for both reading and writing only
    '''
    
    EXCL = 2
    '''
    Fail to create bus if its file already exists
    '''
    
    INTR = 4
    '''
    Fail if interrupted
    '''
    
    NOWAIT = 1
    '''
    Function shall fail with `os.errno.EAGAIN`
    if the it would block and this flag is used
    '''
    
    
    def __init__(self, pathname : str = None):
        '''
        Constructor
        
        @param  pathname:str  The pathname of the bus, `None` if `create` should select a random pathname
        '''
        self.pathname = pathname
        self.bus = None
    
    
    def __del__(self):
        '''
        Destructor
        '''
        self.close()
    
    
    def create(self, flags : int = 0) -> str:
        '''
        Create the bus
        
        @param   flags:or_flag  `Bus.EXCL` (if the pathname is not `None`) to fail if the file
                                already exists, otherwise if the file exists, nothing will happen;
                                `Bus.INTR` to fail if interrupted
        @return  :str           The pathname of the bus
        '''
        from native_bus import bus_create_wrapped
        (self.pathname, e) = bus_create_wrapped(self.pathname, flags)
        if self.pathname is None:
            raise self.__oserror(e)
        return self.pathname
    
    
    def unlink(self):
        '''
        Remove the bus
        '''
        from native_bus import bus_unlink_wrapped
        (r, e) = bus_unlink_wrapped(self.pathname)
        if r == -1:
            raise self.__oserror(e)
    
    
    def open(self, flags : int = 0):
        '''
        Open an existing bus
        
        @param  flags:int  `Bus.RDONLY`, `Bus.WRONLY` or `Bus.RDWR`, the value must not be negative
        '''
        from native_bus import bus_close_wrapped, bus_allocate, bus_open_wrapped
        if self.bus is not None:
            (r, e) = bus_close_wrapped(self.bus)
            if r == -1:
                raise self.__oserror(e)
        else:
            (self.bus, e) = bus_allocate()
            if self.bus == 0:
                raise self.__oserror(e)
        (r, e) = bus_open_wrapped(self.bus, self.pathname, flags)
        if r == -1:
            raise self.__oserror(e)
    
    
    def close(self):
        '''
        Close the bus
        '''
        try:
            from native_bus import bus_close_wrapped, bus_deallocate
        except:
            return
        if self.bus is not None:
            (r, e) = bus_close_wrapped(self.bus)
            if r == -1:
                raise self.__oserror(e)
            bus_deallocate(self.bus)
            self.bus = None
    
    
    def write(self, message : str, flags : int = 0):
        '''
        Broadcast a message a bus
        
        @param  message:str  The message to write, may not be longer than 2047 bytes
                             after UTF-8 encoding
        @param  flags:int    `Bus.NOWAIT` if the function shall fail with `os.errno.EAGAIN`
                             if there is another process attempting to broadcast on the bus
        '''
        from native_bus import bus_write_wrapped
        (r, e) = bus_write_wrapped(self.bus, message, flags)
        if r == -1:
            raise self.__oserror(e)
    
    
    def write_timed(self, message : str, timeout : float, clock_id : int = None):
        '''
        Broadcast a message a bus
        
        @param  message:str    The message to write, may not be longer than 2047 bytes
                               after UTF-8 encoding
        @param  timeout:float  The time the function shall fail with `os.errno.EAGAIN`,
                               if it has not already completed
        @param  clock_id:int?  The clock `timeout` is measured in, it must be a
                               predictable clock, if `None`, `timeout` is measured in
                               relative time instead of absolute time
        '''
        from native_bus import bus_write_timed_wrapped
        if clock_id is None:
            import time
            clock_id = time.CLOCK_MONOTONIC_RAW
            timeout += time.clock_gettime(clock_id)
        (r, e) = bus_write_timed_wrapped(self.bus, message, timeout, clock_id)
        if r == -1:
            raise self.__oserror(e)
    
    
    def read(self, callback : callable, user_data = None):
        '''
        Listen (in a loop, forever) for new message on a bus
        
        @param   callback:(message:str?, user_data:¿U?=user_data)→int
                               Function to call when a message is received, the
                               input parameters will be the read message and
                               `user_data` from the function's [`Bus.read`] parameter
                               with the same name. The message must have been parsed
                               or copied when `callback` returns as it may be over
                               overridden after that time. `callback` should
                               return either of the the values:
                                  0:  stop listening
                                  1:  continue listening
                                 -1:  an error has occurred
                               However, the function [`Bus.read`] will invoke
                               `callback` with `message` set to `None` one time
                               directly after it has started listening on the bus.
                               This is to the the program now it can safely continue
                               with any action that requires that the programs is
                               listening on the bus.
                               NB! The received message will not be decoded from UTF-8
        @param  user_data:¿U?  See description of `callback`
        '''
        from native_bus import bus_read_wrapped
        (r, e) = bus_read_wrapped(self.bus, callback, user_data)
        if r == -1:
            raise self.__oserror(e)
    
    
    def read_timed(self, callback : callable, timeout : float, clock_id : int = None, user_data = None):
        '''
        Listen (in a loop, forever) for new message on a bus
        
        @param   callback:(message:str?, user_data:¿U?=user_data)→int
                               Function to call when a message is received, the
                               input parameters will be the read message and
                               `user_data` from the function's [`Bus.read`] parameter
                               with the same name. The message must have been parsed
                               or copied when `callback` returns as it may be over
                               overridden after that time. `callback` should
                               return either of the the values:
                                  0:  stop listening
                                  1:  continue listening
                                 -1:  an error has occurred
                               However, the function [`Bus.read`] will invoke
                               `callback` with `message` set to `None` one time
                               directly after it has started listening on the bus.
                               This is to the the program now it can safely continue
                               with any action that requires that the programs is
                               listening on the bus.
                               NB! The received message will not be decoded from UTF-8
        @param  timeout:float  The time the function shall fail with `os.errno.EAGAIN`,
                               if it has not already completed, note that the callback
                               function may or may not have been called
        @param  clock_id:int?  The clock `timeout` is measured in, it must be a
                               predictable clock, if `None`, `timeout` is measured in
                               relative time instead of absolute time
        @param  user_data:¿U?  See description of `callback`
        '''
        from native_bus import bus_read_timed_wrapped
        if clock_id is None:
            import time
            clock_id = time.CLOCK_MONOTONIC_RAW
            timeout += time.clock_gettime(clock_id)
        (r, e) = bus_read_timed_wrapped(self.bus, callback, user_data, timeout, clock_id)
        if r == -1:
            raise self.__oserror(e)
    
    
    def poll_start(self):
        '''
        Announce that the thread is listening on the bus.
        This is required so the will does not miss any
        messages due to race conditions. Additionally,
        not calling this function will cause the bus the
        misbehave, is `Bus.poll` is written to expect
        this function to have been called.
        '''
        from native_bus import bus_poll_start_wrapped
        (r, e) = bus_poll_start_wrapped(self.bus)
        if r == -1:
            raise self.__oserror(e)
    
    
    def poll_stop(self):
        '''
        Announce that the thread has stopped listening on the bus.
        This is required so that the thread does not cause others
        to wait indefinitely.
        '''
        from native_bus import bus_poll_stop_wrapped
        (r, e) = bus_poll_stop_wrapped(self.bus)
        if r == -1:
            raise self.__oserror(e)
    
    
    def poll(self, flags : int = 0) -> bytes:
        '''
        Wait for a message to be broadcasted on the bus.
        The caller should make a copy of the received message,
        without freeing the original copy, and parse it in a
        separate thread. When the new thread has started be
        started, the caller of this function should then
        either call `Bus.poll` again or `Bus.poll_stop`.
        
        @param   flags:int  `Bus.NOWAIT` if the bus should fail with `os.errno.EAGAIN`
                            if there isn't already a message available on the bus
        @return  :bytes     The received message
                            NB! The received message will not be decoded from UTF-8
        '''
        from native_bus import bus_poll_wrapped
        (message, e) = bus_poll_wrapped(self.bus, flags)
        if message is None:
            raise self.__oserror(e)
        return message
    
    
    def poll_timed(self, timeout : float, clock_id : int = None) -> bytes:
        '''
        Wait for a message to be broadcasted on the bus.
        The caller should make a copy of the received message,
        without freeing the original copy, and parse it in a
        separate thread. When the new thread has started be
        started, the caller of this function should then
        either call `Bus.poll_timed` again or `Bus.poll_stop`.
        
        @param   timeout:float  The time the function shall fail with `os.errno.EAGAIN`,
                                if it has not already completed
        @param   clock_id:int?  The clock `timeout` is measured in, it must be a
                                predictable clock, if `None`, `timeout` is measured in
                                relative time instead of absolute time
        @return  :bytes         The received message
                                NB! The received message will not be decoded from UTF-8
        '''
        from native_bus import bus_poll_timed_wrapped
        if clock_id is None:
            import time
            clock_id = time.CLOCK_MONOTONIC_RAW
            timeout += time.clock_gettime(clock_id)
        (message, e) = bus_poll_timed_wrapped(self.bus, timeout, clock_id)
        if message is None:
            raise self.__oserror(e)
        return message
    
    
    def chown(self, owner = None, group = None):
        '''
        Change the ownership of a bus
        
        `os.stat` can be used of the bus's associated file to get the bus's ownership
        
        @param  owner:int|str?      The user ID or username of the bus's new owner,
                                    if `None`, keep current
        @param  group:int|str|...?  The group ID or groupname of the bus's new group,
                                    if `None`, keep current, `...` to use the owner's group
        '''
        from native_bus import bus_chown_wrapped
        if (owner is None) or (group is None):
            from os import stat
            attr = stat(self.pathname)
            if owner is None:  owner = attr.st_uid
            if group is None:  group = attr.st_gid
        if isinstance(owner, str):
            import pwd
            owner = pwd.getpwnam(owner).pw_uid
        if isinstance(group, str):
            import grp
            group = grp.getgrnam(group).gr_gid
        elif group is ...:
            import pwd
            group = pwd.getpwuid(owner).pw_gid
        (r, e) = bus_chown_wrapped(self.pathname, owner, group)
        if r == -1:
            raise self.__oserror(e)
    
    
    def chmod(self, mode : int, mask : int = None):
        '''
        Change the permissions for a bus
        
        `os.stat` can be used of the bus's associated file to get the bus's permissions
        
        @param  mode:int   The permissions of the bus, any permission for a user implies
                           full permissions for that user, except only the owner may
                           edit the bus's associated file
        @param  mask:int?  Bits to clear before setting the bits in `mode`, if `None`,
                           all bits are cleared
        '''
        from native_bus import bus_chmod_wrapped
        if mask is not None:
            from os import stat
            current = stat(self.pathname).st_mode
            if current & 0o700:  current |= 0o700
            if current &  0o70:  current |=  0o70
            if current &   0o7:  current |=   0o7
            if mask & 0o700:  mask |= 0o700
            if mask &  0o70:  mask |=  0o70
            if mask &   0o7:  mask |=   0o7
            current &= ~mask
            mode |= current
        (r, e) = bus_chmod_wrapped(self.pathname, mode)
        if r == -1:
            raise self.__oserror(e)
    
    
    def __oserror(self, err : int):
        '''
        Create an OSError
        
        @param   err:int   The value of errno
        @return  :OSError  The OS error
        '''
        import os
        err = OSError(err, os.strerror(err))
        if err.errno == os.errno.ENOENT:
            err.filename = self.pathname
        return err