Bytearray API:

Module shared_atomic.atomic_bytearray on Linux and macOS

class shared_atomic.atomic_bytearray.atomic_bytearray

string provide atomic operations, the string should be no longer than 8 bytes

:attributes

initial_byte_length: readonly initial input length as number of bytes it took

value: read/write value of the string

int_value: readonly integer representation of the atomic_bytearray

constructor to initialize the string, the string should be no longer than 8 bytes

Parameters

  • initial – initial value of the string, if the initial value is longer than 8 bytes, please specify the trimming target length, or else it would fail.

  • mode – the mode in which the string will be shared. ‘singleprocessing’ or ‘s’ for single process, ‘multiprocessing’ or ‘m’ for multiprocessing, on windows platform, only singleprocessing is supported, setting it to ‘m’ or ‘multiprocessing’ will be ignored.

  • length – the expected length after padding/trimming for the input value, if not specified, no padding or trimming performed, use original value.

  • paddingdirection – right, or left side the padding bytes would be added if not specified, pad to the right side, use ‘right’ or ‘r’ to specify right side, use ‘left’ or ‘l’ to specify the left side.

  • paddingbytes – bytes to pad to the original bytes, by default ‘\0’ can be multiple bytes like b’ab’, will be padded to the original bytes in circulation until the expected length is reached.

  • trimming_direction – if initial bytes are longer, on which side the bytes will be trimmed. By default, on the right side, use ‘right’ or ‘r’ to specify right side, use ‘left’ or ‘l’ to specify the left side.

  • windows_unix_compatibility – dummy parameter on unix platform, used on windows platform to indicate whether the source code should be compatible with unix platform

array_add_and_fetch()

Increment and fetch atomically

Parameters

  • n – bytes will be added to the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

array_and_and_fetch()

Bitwise AND and fetch the result atomically

Parameters

  • n – the other operand of AND operation.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

array_compare_and_set()

Compare and set atomically,This compares the contents of self with the contents of i. If equal, the operation is a read-modify-write operation that writes n into self. If they are not equal, the operation is a read and the current contents of itself are written into i.

Parameters

i – the bytearray to be compared with

Returns

if self is equal to i return True, else return False

array_compare_and_set_value()

Compare and swap atomically, This compares the contents of self with the contents of n. If equal, the operation is a read-modify-write operation that writes n into self. If they are not equal, No operation will be performed.

Parameters

  • i – exchange value

  • n – The value to be compared with

  • trim – whether the returned bytes should be trimmed of tailing b’\0’

Returns

the initial value of the self

array_fetch_and_add()

fetch and increment atomically

Parameters

  • n – the bytes will be added to the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_and()

Fetch then bitwise AND atomically

Parameters

  • n – the other operands of AND operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_nand()

fetch then bitwise NAND atomically

Parameters

  • n – the other operands of NAND operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_or()

Fetch then bitwise OR atomically

Parameters

  • n – the other operands of OR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_sub()

fetch and decrement atomically

Parameters

  • n – the bytes will be substracted from the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_xor()

Fetch then bitwise XOR atomically

Parameters

  • n – the other operands of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_get_and_set()

Get and set atomically

Parameters

  • data – new data

  • trim – whether of not to trim the returning b’\0’ when get, default True

Returns

the original bytes

array_nand_and_fetch()

bitsise NAND and fetch the result atomically

Parameters

  • n – the other operand of NAND operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

array_or_and_fetch()

bitsise OR and fetch the result atomically

Parameters

  • n – the other operand of OR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

array_shift()

Value exchange between 3 bytearrays in 2 groups atomically, the initial_length field will be updated but not atomically. store i in itself after store itself in j

Parameters

  • i – one atomic_bytearray

  • j – another atomic_bytearray

Returns

None

array_store()

Atomically store contents from another bytearray to this bytearray, if the other bytearray is different with this one in size , the function will fail.

Parameters

i – another bytearray to store its value to self

Returns

None

array_sub_and_fetch()

Decrement and fetch atomically

Parameters

  • n – bytes will be subtracted from the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

array_xor_and_fetch()

bitsise XOR and fetch the result atomically

Parameters

  • n – the other operand of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

get_bytes()

Get all the bytes from the bytearray atomically

Parameters

trim – if True, the leading b’\0’ would be trimmed, by default: True

Returns

all the bytes in the bytearray

get_int()

Get the integer representation from the bytearray, the whole array would be treated as a large integer

Returns

the integer representation

resize()

trim or pad the original contents in the bytearray to a new length, the new length should be no longer than 8 bytes, the original array wll be replaced with new array, if the original array is shared between threads/processes, other threads/processes will wouldn’t be aware of the change, still use the old bytearray.

Parameters

  • newlength – the expected new length of the original bytes.

  • paddingdirection – if longer than original, left or right sidethe original bytes should be padded, by default right side,use ‘right’ or ‘r’ to specify right side, use ‘left’ or ‘l’ to specify the left side.

  • paddingbytes – bytes to pad to the original bytes, by default b’\0’ can be multiple bytes like b’ab’, will be padded to the original bytes in circulation until the expected length is reached.

  • trimming_direction – if shorted than original, left or right side the original bytes should be padded,use ‘right’ or ‘r’ to specify right side,use ‘left’ or ‘l’ to specify the left side.

Returns

None

set_bytes()

Set the value in the bytearray, if the new data is longer than the original size of the array. it will expand the array accordingly which would lose atomicy. the size of the bytearray can be check with self.size

Parameters

data – input bytearray

Returns

None

shared_atomic.atomic_bytearray.array_add_and_fetch()

Increment and fetch atomically

Parameters

  • array – target array to change.

  • n – bytes will be added to the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

shared_atomic.atomic_bytearray.array_and_and_fetch()

Bitwise and and then fetch atomically

Parameters

  • array – target array to change.

  • n – the other operands of AND operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_compare_and_set()

Compare and set atomically, this compares the contents of j with the contents of i. If equal, the operation is a read-modify-write operation that writes n into self. If they are not equal, the operation is a read and the current contents of j are written into i.

Parameters

  • array – target array to change.

  • i – the string to compare

  • j – the string to be compared with

  • data – another bytes to be ready to self if comparision return True

Returns

if self is equal to i return True, else return False

shared_atomic.atomic_bytearray.array_compare_and_set_value()

Compare and set atomically,This compares the contents of self with the contents of i. If equal, the operation is a read-modify-write operation that writes n into self. If they are not equal, the operation is a read and the current contents of itself are written into i.

Parameters

  • array – target array to change.

  • i – The exchange value

  • n – The value to compare to

  • trim – whether the returned bytes should be trimmed of tailing b’\0’

Returns

Original value

shared_atomic.atomic_bytearray.array_fetch_and_add()

fetch and increment atomically

Parameters

  • array – target array to change.

  • n – the bytes will be added to the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_and()

Fetch then bitwise AND atomically

Parameters

  • array – target array to change.

  • n – the other operands of AND operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_nand()

Fetch then bitwise NAND atomically

Parameters

  • array – target array to change.

  • n – the other operands of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_or()

Fetch then bitwise OR atomically

Parameters

  • array – target array to change.

  • n – the other operands of OR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_sub()

fetch and decrement atomically

Parameters

  • array – target array to change.

  • n – the bytes will be substracted from the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_xor()

Fetch then bitwise XOR atomically

Parameters

  • array – target array to change.

  • n – the other operands of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_get_and_set()

Get and set atomically

Parameters

  • array – target array to change.

  • data – new data

  • trim – if True, the leading b’\0’ would be trimmed, by default: True

Returns

the original bytes

shared_atomic.atomic_bytearray.array_get_bytes()

Get all the bytes from the bytearray atomically

Parameters

  • array – target array.

  • trim – if True, the leading b’\0’ would be trimmed, by default: True

Returns

all the bytes in the bytearray

shared_atomic.atomic_bytearray.array_get_int()

Get the integer representation from the bytearray, the whole array would be treated as a large integer

Parameters

array – target array.

Returns

the integer representation

shared_atomic.atomic_bytearray.array_nand_and_fetch()

Bitwise nand and then fetch atomically

Parameters

  • array – target array to change.

  • n – the other operands of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_or_and_fetch()

Bitwise or and then fetch atomically

Parameters

  • array – target array to change.

  • n – the other operands of OR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_set_bytes()

Set the bytes for the bytearray,

Parameters

  • array – target array.

  • data – bytes to set the data.

Returns

None

shared_atomic.atomic_bytearray.array_shift()

Value exchange between 3 pointers in 2 groups atomically, the initial_length field will be updated but not atomically. store i in n after store n in j

Parameters

  • n – one atomic_string

  • i – one atomic_string

  • j – another atomic_string

Returns

None

shared_atomic.atomic_bytearray.array_store()

Set the bytes for the bytearray from another bytearray,

Parameters

  • n – target array.

  • i – source array.

Returns

None

shared_atomic.atomic_bytearray.array_sub_and_fetch()

Decrement and fetch atomically

Parameters

  • array – target array to change.

  • n – bytes will be subtracted from the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

shared_atomic.atomic_bytearray.array_xor_and_fetch()

Bitwise xor and then fetch atomically

Parameters

  • array – target array to change.

  • n – the other operands of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

On Microsoft Windows

class shared_atomic.atomic_bytearray.atomic_bytearray

bytearray provide atomic operations, the bytearray should be no longer than 8 bytes

:attributes

initial_length: readonly initial input length int_value: readonly the byte value of value: readonly initial input length

constructor to initialize the bytearray, the bytearray should be no longer than 8 bytes

Parameters

  • initial – initial value of the bytearray, if the initial value is longer than 8 bytes, please specify the trimming target length, or else it would fail.

  • mode – the mode in which the bytearray will be shared. ‘singleprocessing’ or ‘s’ for single process, ‘multiprocessing’ or ‘m’ for multiprocessing, on windows platform, only singleprocessing is supported.

  • length – the expected length after padding/trimming for the input value, if not specified, no padding or trimming performed, use original value.

  • paddingdirection – right, or left side the padding bytes would be added if not specified, pad to the right side, use ‘right’ or ‘r’ to specify right side, use ‘left’ or ‘l’ to specify the left side.

  • paddingbytes – bytes to pad to the original bytes, by default b’\0’ can be multiple bytes like b’ab’, will be padded to the original bytes in circulation until the expected length is reached.

  • trimming_direction – if initial bytes are longer, on which side the bytes will be trimmed. By default, on the right side, use ‘right’ or ‘r’ to specify right side, use ‘left’ or ‘l’ to specify the left side.

  • windows_unix_compatibility – whether the source code should be compatible with unix platform

array_add_and_fetch()

Increment and fetch atomically

Parameters

  • n – bytes will be added to the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

array_bittest_and_reset()

Tests the specified bit and sets it to 0 atomically

Parameters

offset – offset in the binary presenation of the bytearray

Returns

the initial value(True or False) of specified bit

array_bittest_and_set()

Tests the specified bit and sets it to 1 atomically

Parameters

offset – offset in the binary presenation of the bytearray

Returns

the initial value(True or False) of specified bit

array_compare_and_set_value()

Compare and swap atomically, This compares the contents of self with the contents of n. If equal, the operation is a read-modify-write operation that writes n into self. If they are not equal, No operation will be performed.

Parameters

  • i – exchange value

  • n – The value to be compared with

  • trim – whether the returned bytes should be trimmed of tailing b’0’

Returns

the initial value of the self

array_fetch_and_add()

fetch and increment atomically

Parameters

  • n – the bytes will be added to the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_and()

fetch and increment atomically

Parameters

  • n – the bytes will be added to the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_or()

Fetch then bitwise OR atomically

Parameters

  • n – the other operands of OR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_sub()

fetch and increment atomically

Parameters

  • n – the bytes will be added to the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_fetch_and_xor()

Fetch then bitwise XOR atomically

Parameters

  • n – the other operands of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

array_get_and_set()

Get and set atomically

Parameters

  • data – new data

  • trim – whether of not to trim the returning b’\0’ when get, default True

Returns

the original bytes

array_sub_and_fetch()

Decrement and fetch atomically

Parameters

  • n – bytes will be subtracted from the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

get_bytes()

Get all the bytes from the bytearray atomically

Parameters

trim – if True, the leading b’\0’ would be trimmed, by default: True

Returns

all the bytes in the bytearray

get_int()

Get the integer representation from the bytearray, the whole array would be treated as a large integer

Returns

the integer representation

resize()

trim or pad the original contents in the bytearray to a new length, the new length should be no longer than 8 bytes, the original array wll be replaced with new array, if the original array is shared between threads/processes, other threads/processes will wouldn’t be aware of the change, still use the old bytearray.

Parameters

  • newlength – the expected new length of the original bytes.

  • paddingdirection – if longer than original, left or right sidethe original bytes should be padded, by default right side,use ‘right’ or ‘r’ to specify right side, use ‘left’ or ‘l’ to specify the left side.

  • paddingbytes – bytes to pad to the original bytes, by default b’\0’ can be multiple bytes like b’ab’, will be padded to the original bytes in circulation until the expected length is reached.

  • trimming_direction – if shorted than original, left or right side the original bytes should be padded,use ‘right’ or ‘r’ to specify right side,use ‘left’ or ‘l’ to specify the left side.

Returns

None

set_bytes()

Set the value in the bytearray, if the new data is longer than the original size of the array. it will expand the array accordingly which would lose atomicity. the size of the bytearray can be checked with self.size

Parameters

data – input bytearray

Returns

None

shared_atomic.atomic_bytearray.array_add_and_fetch()

Increment and fetch atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • n – bytes will be added to the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray

shared_atomic.atomic_bytearray.array_bittest_and_reset()

bittest_and_reset the original contents in the bytearray

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • offset – offset from counted by bits from the left.

Returns

original value(True or False) at the offset

shared_atomic.atomic_bytearray.array_bittest_and_set()

bittest_and_set the original contents in the bytearray

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • offset – offset from counted by bits from the left.

Returns

original value(True or False) at the offset

shared_atomic.atomic_bytearray.array_compare_and_set_value()

Compare and set atomically,This compares the contents of self with the contents of i. If equal, the operation is a read-modify-write operation that writes n into self. If they are not equal, the operation is a read and the current contents of itself are written into i.

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • i – The exchange value

  • n – The value to compare to

  • trim – whether the returned bytes should be trimmed of tailing b’

shared_atomic.atomic_bytearray.array_fetch_and_add()

fetch and increment atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • n – the bytes will be added to the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_and()

Fetch then bitwise AND atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • n – the other operands of AND operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_or()

Fetch then bitwise OR atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • n – the other operands of OR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_sub()

fetch and decrement atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • n – the bytes will be substracted from the array

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_fetch_and_xor()

Fetch then bitwise XOR atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • n – the other operands of XOR operation

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the original contents of the bytearray

shared_atomic.atomic_bytearray.array_get_and_set()

Get and set atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • data – new data

  • trim – if True, the leading b’\0’ would be trimmed, by default: True

Returns

the original bytes

shared_atomic.atomic_bytearray.array_get_bytes()

Get all the bytes from the bytearray atomically

Parameters

  • array – target array.

  • reference – reference got by the subprocess .

  • trim – if True, the leading b’\0’ would be trimmed, by default: True

Returns

all the bytes in the bytearray

shared_atomic.atomic_bytearray.array_get_int()

Get the integer representation from the bytearray, the whole array would be treated as a large integer

Parameters

  • array – target array.

  • reference – reference got by the subprocess .

Returns

the integer representation

shared_atomic.atomic_bytearray.array_set_bytes()

Set the bytes for the bytearray,

Parameters

  • array – target array.

  • reference – reference got by the subprocess.

  • data – bytes to set the data.

Returns

None

shared_atomic.atomic_bytearray.array_sub_and_fetch()

Decrement and fetch atomically

Parameters

  • array – target array to change.

  • reference – reference got by the subprocess.

  • n – bytes will be subtracted from the array.

  • trim – whether of not to trim the returning b’\0’ when fetch, default True

Returns

the contents of resulted bytearray