SyncInt

class thread_factory.concurrency.sync_types.sync_int.SyncInt(*args, **kwargs)

Bases: ISync

🔐 Core Purpose

SyncInt provides synchronized access to integer operations, ensuring that multiple threads can safely read and modify the value without race conditions.

🔧 Features

• Full support for arithmetic operations (+, -, *, //, %, **, etc.)

• Comparison operators (==, <, >, etc.)

• Bitwise operations (&, |, ^, <<, >>)

• Type conversion (int(), float(), str())

• Manual and atomic value access via .get() and .set()

• Safe thread-aware binary operations with locking on both operands

⚡ Power Operation Support

SyncInt includes custom implementations for __pow__ and __rpow__:

• __pow__: Handles SyncInt ** x — supports optional modulo as a third argument.

• __rpow__: Handles x ** SyncInt when x cannot handle the pow itself.

⚠️ Important Limitation (Python dispatch rule)

The built-in pow() function in Python always dispatches based on the left-most operand. This means:

✅ pow(SyncInt, …, …) ➜ will invoke SyncInt.__pow__ ✅ 3 ** SyncInt ➜ will invoke SyncInt.__rpow__ (if int.__pow__ fails) ❌ pow(3, SyncInt, 5) ➜ SyncInt methods are NOT called (fails with TypeError)

To work around these dispatch limitations for ternary power (pow(a, b, c)), use:

SyncInt.safe_pow(a, b, c)

This static utility: - Unwraps all SyncInt arguments - Acquires all relevant locks (if needed) - Performs the operation correctly, regardless of argument order

🧠 Deadlock Prevention

For binary and ternary operations involving multiple SyncInt instances, locks are always acquired in order of object ID to avoid deadlocks.

This makes operations like SyncInt(3) ** SyncInt(4) % SyncInt(5) safe across threads.

✅ Recommended Usage:

result = SyncInt.safe_pow(a, b, c) # Always works result = SyncInt(4) ** SyncInt(3) % 5 # Works if base is SyncInt result = 3 ** SyncInt(3) # Works (calls __rpow__) pow(3, SyncInt(3), 5) # ❌ Will raise TypeError

as_integer_ratio()

Return a pair of integers, whose ratio is equal to the original int.

The ratio is in lowest terms and has a positive denominator.

>>> SyncInt(10).as_integer_ratio()
(10, 1)
>>> SyncInt(-10).as_integer_ratio()
(-10, 1)
>>> SyncInt(0).as_integer_ratio()
(0, 1)

bit_count()

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> SyncInt(13).bit_count()
3

bit_length()

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> SyncInt(37).bit_length()
6

conjugate()

Returns self, the complex conjugate of any int.

For all integers, this is just self.

decrement(value=1)

Atomically decrement the internal value by the specified amount.

Parameters:

value (int or SyncInt) – The amount to subtract.

Returns:

The updated value after decrement.

Return type:

int

property denominator

The denominator of the rational representation.

Returns:

Denominator (always 1 for ints).

Return type:

int

classmethod from_bytes(b: bytes, byteorder: str, *, signed: bool = False)

Return the integer represented by the given array of bytes.

Parameters:

• b (bytes) – The byte array to convert.

• byteorder (str) – ‘big’ or ‘little’.

• signed (bool) – Whether the integer is signed.

Returns:

A new SyncInt representing the decoded value.

Return type:

SyncInt

get() → int

Return the current integer value in a thread-safe way.

Returns:

The stored integer value.

Return type:

int

property imag

The imaginary part of the number.

Returns:

Always 0 for integers.

Return type:

int

increment(value=1)

Atomically increment the internal value by the specified amount.

Parameters:

value (int or SyncInt) – The amount to add.

Returns:

The updated value after increment.

Return type:

int

is_integer()

Always True. Exists for compatibility with float.

Returns:

Always True for integers.

Return type:

bool

property numerator

The numerator of the rational representation.

Returns:

Numerator.

Return type:

int

property real

The real part of the number.

Returns:

Real value (itself).

Return type:

int

static safe_pow(base, exp, mod=None)

Thread-safe pow() that locks all SyncInt operands (if any) using consistent locking order.

Parameters:

• base (int or SyncInt) – Base value.

• exp (int or SyncInt) – Exponent.

• mod (int or SyncInt, optional) – Modulo.

Returns:

Result of pow(base, exp, mod) or pow(base, exp)

Return type:

int

set(new_value: int)

Set a new integer value in a thread-safe way.

Parameters:

new_value (int) – The new value to assign.

to_bytes(length: int, byteorder: str, *, signed: bool = False)

Return an array of bytes representing an integer.

Parameters:

• length (int) – Desired byte length of the output.

• byteorder (str) – ‘big’ or ‘little’.

• signed (bool) – Whether to use two’s complement.

Returns:

The byte representation of the stored integer.

Return type:

bytes