String API:

Module shared_atomic

class shared_atomic.atomic_string. atomic_string ( initial : unicode , mode : unicode = 'singleprocessing' , length : int = None , paddingdirection : unicode = 'right' , paddingstr : unicode = ' ' , trimming_direction : unicode = 'right' , encoding = 'utf-8' , windows_unix_compatibility : bool = False )

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

encoding: readonly string character set

size: readonly size of the string

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

value: read/write value of the string

mode: readonly ‘s’ for single process, ‘m’ for multiprocessing, on windows platform, only singleprocessing is supported

windows_unix_compatibility: readonly whether the source code should be compatible with windows x64

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 windows x64

change_mode ( newmode = 'm' , windows_unix_compatibility : bool = False )

Switch between singleprocessing mode and multiprocessing mode, the function doesn’t exists on windows, since only single processing mode is supported on windows platform. the contents will be copied , other threads/processes would not be aware of the change.

Parameters

newmode – the mode to change to, ‘m’ for multiproessing, ‘s’ for singleprocessing. default ‘m’

Returns

None

get_string ( )

Get all the bytes from the string atomically

Returns

all the bytes in the string

reencode ( newencode : unicode )

Change the encoding of the string, if the original size is not enough, it will elongate the string, which is only valid in the master process/thread, if 7 bytes are not enough, it will fail.

Parameters

newencode – new encoding, such as ‘utf-8’, ‘utf-16-le’

Returns

None

resize ( newlength : char , paddingdirection : unicode = 'right' , paddingstr : unicode = ' ' , trimming_direction : unicode = 'right' )

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, only valid for the master process/thread

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_string ( data : unicode )

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 could only be used in the master process/thread the size of the string can be check with self.size

Parameters

data – input string

Returns

None

string_compare_and_set ( i : self_atomic_string , n : unicode ) → bool

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 string to be compared with

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

Returns

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

string_compare_and_set_value ( i : unicode , n : unicode ) → unicode

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 i into self. If they are not equal, No operation is performed.

Parameters

• i – exchange value

• n – The value to be compared with

Returns

the initial value of self

string_get_and_set ( data : unicode ) → unicode

Get and set atomically

Parameters

data – new data

Returns

the original string

string_shift ( i : self_atomic_string , j : self_atomic_string )

Value exchange between 3 pointers 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_string

• j – another atomic_string

Returns

None

string_store ( i : self_atomic_string )

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

Parameters

i – another string to store its value to self

Returns

property value

same with get_string and set_string