roboglia.base.SharedBus¶
-
class
SharedBus
(BusClass, timeout=0.5, **kwargs)[source]¶ Bases:
object
Implements a bus that provides a locking mechanism for the access to the underlying hardware, aimed specifically for use in multi-threaded environments where multiple jobs could compete for access to one single bus.
Note
This class implements
__getattr__
so that any calls to an instance of this class that are not already implemented bellow will be passed to the internal instance ofBusClass
that was created at instantiation. This way you can access all the attributes and methods of theBusClass
instance transparently, as long as they are not already overridden by this class.- Parameters
BusClass (BaseBus subclass) – The class that will be wrapped by the
SharedBus
timeout (float) – A timeout for acquiring the lock that controls the access to the bus
**kwargs – keyword arguments that are passed to the BusClass for instantiation
-
__init__
(BusClass, timeout=0.5, **kwargs)[source]¶ Initialize self. See help(type(self)) for accurate signature.
-
property
timeout
¶ Returns the timeout for requesting access to lock.
-
can_use
()[source]¶ Tries to acquire the resource on behalf of the caller.
This method should be called every time a user of the bus wants to perform an operation. If the result is
False
the user does not have exclusive use of the bus and the actions are not guaranteed.Warning
It is the responsibility of the user to call
stop_using()
as soon as possible after preforming the intended work with the bus if this method grants it access. Failing to do so will result in the bus being blocked by this user and prohibiting other users to access it.- Returns
True
if managed to acquire the resource,False
if not. It is the responsibility of the caller to decide what to do in case there is aFalse
return including logging or Raising.- Return type
bool
-
naked_read
(reg)[source]¶ Calls the main bus read without invoking the lock. This is intended for those users that plan to use a series of read operations and they do not want to lock and release the bus every time, as this adds some overhead. Since the original bus’
read
method is overridden (see below), any calls toread
from a user will result in using the wrapped version defined in this class. Therefore in the scenario that the user wants to execute a series of quick reads thenaked_read
can be used as long as the user wraps the calls correctly for obtaining exclusive access:if bus.can_use(): val1 = bus.naked_read(reg1) val2 = bus.naked_read(reg2) val3 = bus.naked_read(reg3) ... bus.stop_using() else: logger.warning('some warning')
- Parameters
reg (BaseRegister or subclass) – The register object that needs to be read. Keep in mind that the register object also contains a reference to the device in the
device
attribute and it is up to the subclass to determine the way the information must be processed before providing it to the caller.- Returns
Typically it would return an
int
that will have to be handled by the caller.- Return type
int
-
naked_write
(reg, value)[source]¶ Calls the main bus write without invoking the lock. This is intended for those users that plan to use a series of write operations and they do not want to lock and release the bus every time, as this adds some overhead. Since the original bus’
write
method is overridden (see below), any calls towrite
from a user will result in using the wrapped version defined in this class. Therefore in the scenario that the user wants to execute a series of quick writes thenaked_write
can be used as long as the user wraps the calls correctly for obtaining exclusive access:if bus.can_use(): val1 = bus.naked_write(reg1, val1) val2 = bus.naked_write(reg2, val2) val3 = bus.naked_write(reg3, val3) ... bus.stop_using() else: logger.warning('some warning')
- Parameters
reg (BaseRegister or subclass) – The register object that needs to be read. Keep in mind that the register object also contains a reference to the device in the
device
attribute and it is up to the subclass to determine the way the information must be processed before providing it to the caller.value (int) – The value needed to the written to the device.
-
read
(reg)[source]¶ Overrides the main bus’
read()
method and performs a safe read by wrapping the read call in a request to acquire the bus.If the method is not able to acquire the bus in time (times out) it will log an error and return
None
.- Parameters
reg (BaseRegister or subclass) – The register object that needs to be read. Keep in mind that the register object also contains a reference to the device in the
device
attribute and it is up to the subclass to determine the way the information must be processed before providing it to the caller.- Returns
The value read for this register or
None
is the call failed to secure with bus within thetimeout
.- Return type
int
-
write
(reg, value)[source]¶ Overrides the main bus’ ~roboglia.base.BaseBus.write method and performs a safe write by wrapping the main bus write call in a request to acquire the bus.
If the method is not able to acquire the bus in time (times out) it will log an error.
- Parameters
reg (BaseRegister or subclass) – The register object that needs to be read. Keep in mind that the register object also contains a reference to the device in the
device
attribute and it is up to the subclass to determine the way the information must be processed before providing it to the caller.value (int) – The value to be written to the device.