# -*- 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
