String API:¶
Module shared_atomic.atomic_string on Linux and macOS
string provide atomic operations, the string should be no longer than 8 bytes
- :attributes
encoding: readonly string character set
initial_byte_length: readonly initial input length as number of bytes it took
value: read/write value of the string
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.
paddingstr – string 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.
encoding – charactor encoding to store the string, use ‘utf-8’ by default.
windows_unix_compatibility – dummy parameter on linux and macOS, used on windows to indicate whether needs to be compatible with linux and macOS.
Get all the bytes from the string atomically
- Returns
all the bytes in the string
Change the encoding of the string, if the original size is not enough, it will elongate the string, if 7 bytes are not enough, it will fail.
- Parameters
newencode – new encoding, such as ‘utf-8’, ‘utf-16-le’
- Returns
None
trim or pad the original contents in the string to a new length, the new length should be no longer than 8 bytes, the original string wll be replaced with new string, if the original string is shared between threads/processes, other threads/processes will wouldn’t be aware of the change, still use the old string.
- 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.
paddingstr – 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 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 the value in the string, if the new data is longer than the original size of the string. it will expand the string accordingly which would lose atomicity. the size of the string can be check with self.size
- Parameters
data – input string
- Returns
None
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 self are written into i.
- Parameters
i – the string to be compared with
n – another string to be write to j if comparision return True
- Returns
if j is equal to n return True, else return False
Compare and swap atomically, This compares the contents of subprocess reference with the contents of n. If equal, the operation is a read-modify-write operation that writes i into self. If they are not equal, No operation is performed.
- Parameters
i – The exchange value
n – the value to be compared with
- Returns
the initial value
Get and set atomically
- Parameters
data – new data
- Returns
the original string
Value exchange between 3 atomic_strings in 2 groups atomically, the initial_length field will be updated but not atomically. store self in n after store n in self
- Parameters
i – one atomic_string
j – another atomic_string
- Returns
None
Atomically set the data in self from atomic_string i
- Parameters
i – atomic_string from which the data is from
- Returns
None
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 j. If they are not equal, the operation is a read and the current contents of j are written into i.
- Parameters
string – target string.
j – the string to be compared
i – the string to be compared with
n – another string to be write to j if comparision return True
- Returns
if j is equal to n return True, else return False
Compare and swap atomically, This compares the contents in atomic_string string with the contents of n. If equal, the operation is a read-modify-write operation that writes i into self. If they are not equal, No operation is performed.
- Parameters
string – target string.
i – The exchange value
n – the value to be compared with
- Returns
the original string
Get and set atomically
- Parameters
string – target string.
data – new data
- Returns
the original string
Get all the bytes from the string atomically
- Parameters
string – target string.
- Returns
the full string
Set the bytes value in the string, if the new data is longer than the original size of the string. it will expand the string accordingly which would lose atomicity. the size of the string can be check with self.size
- Parameters
string – target string.
data – value to set to
- Returns
None
Value exchange between 3 atomic_strings 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
Atomically set the data in atomic_string n from atomic_string i
- Parameters
n – target atomic_string.
i – atomic_string from which the data is from
- Returns
None
On Microsoft Windows
string provide atomic operations, the string should be no longer than 8 bytes :attributes
encoding: readonly string character set
initial_byte_length: readonly initial input length as number of bytes it took
value: read/write value of the string
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.
paddingstr – string 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.
encoding – charactor encoding to store the string, use ‘utf-8’ by default.
windows_unix_compatibility – whether the source code should be compatible with unix platform
Get the string from the atomic_string atomically
- Returns
all the string
Change the encoding of the string, if the original size is not enough, it will elongate the string, if 7 bytes are not enough, it will fail.
- Parameters
newencode – new encoding, such as ‘utf-8’, ‘utf-16-le’
- Returns
None
trim or pad the original contents in the string to a new length, the new length should be no longer than 8 bytes, the original string wll be replaced with new string, if the original string is shared between threads/processes, other threads/processes will wouldn’t be aware of the change, still use the old string.
- 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.
paddingstr – 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 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 the value in the string, if the new data is longer than the original size of the string. it will expand the string accordingly which would lose atomicity. the size of the string can be check with self.size
- Parameters
data – input string
- Returns
None
Compare and swap atomically, This compares the contents of subprocess reference with the contents of n. If equal, the operation is a read-modify-write operation that writes i into self. If they are not equal, No operation is performed.
- Parameters
i – The exchange value
n – the value to be compared with
- Returns
the initial value
Get and set atomically
- Parameters
data – new data
- Returns
the original string
Compare and swap atomically, This compares the contents in subprocess_reference reference with the contents of n. If equal, the operation is a read-modify-write operation that writes i into self. If they are not equal, No operation is performed.
- Parameters
string – target string.
reference – the reference used in subprocess.
i – The exchange value
n – the value to be compared with
- Returns
the original string
Get and set atomically
- Parameters
string – target string.
reference – the reference used in subprocess.
data – new data
- Returns
the original string
Get all the bytes from the string atomically
- Parameters
string – target string.
reference – the reference used in subprocess
- Returns
the full string
Set the bytes value in the string, if the new data is longer than the original size of the string. it will expand the string accordingly which would lose atomicity. the size of the string can be check with self.size
- Parameters
string – target string.
reference – the reference used in subprocess.
data – value to set to
- Returns
None
