APIs¶

refcount module¶

`refcount`¶

A simple library for providing a reference counter with optional acquire/release callbacks as well as access protection to reference counted values.

class refcount.RefcountedValue(value, usecount=1, acquire=None, release=None)¶

Bases: refcount.Refcounter

Provides access protection to a reference counted value.

Allows the reference counting for a value to be arbitrarily incremented and decremented, permitting access to the protected value so long as a valid reference count is held. Once the reference count has dropped to 0, continued references will raise a NameError exception. A release callback method may optionally be provided, and will be called as soon as the last remaining reference is dropped.

add(value)¶

Add to a reference count

If the reference count becomes higher than 0, the acquire callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.add(2)
>>> ref.usecount
3

Parameters:	value (int) – Amount to add

add_not_zero(value)¶

Add to a reference count unless it is 0

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.dec()
>>> ref.usecount
0
>>> ref.add_not_zero(2)
False

Parameters:	value (int) – Amount to add
Returns:	False if refcount is 0, True otherwise

dec()¶

Decrement reference count by 1

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> def refcount_released():
...     print('no more users')
>>> ref = Refcounter(release=refcount_released)
>>> ref.inc()
>>> ref.dec()
>>> ref.dec()
no more users

Raises:	UnderflowException – refcount underflow

dec_and_test()¶

Decrement reference count and test if the reference count is 0

This can be used by code that wishes to implement a cleanup path triggered only when the reference count drops to 0.

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> if ref.dec_and_test():
...     print('reference count is now 0')
reference count is now 0

Returns:	True if reference count is 0, otherwise False
Return type:	bool
Raises:	UnderflowException – refcount underflow

inc()¶

Increment reference count by 1

If the reference count becomes higher than 0, the acquire callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.usecount
1
>>> ref.inc()
>>> ref.usecount
2

inc_not_zero()¶

Increment a reference by 1 unless it is 0

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.dec()
>>> ref.usecount
0
>>> ref.inc_not_zero()
False

Returns:	False if refcount is 0, True otherwise

sub(value)¶

Subtract from a reference count

>>> from refcount import Refcounter
>>> ref = Refcounter(usecount=3)
>>> ref.usecount
3
>>> ref.sub(2)
>>> ref.usecount
1

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

Parameters:	value (int) – Amount to subtract
Raises:	UnderflowException – refcount underflow

sub_and_test(value)¶

Subtract reference count and test if the reference count is 0

This can be used by code that wishes to implement a cleanup path triggered only when the reference count drops to 0.

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.inc()
>>> if ref.sub_and_test(2):
...     print('reference count is now 0')
reference count is now 0

Parameters:	value (int) – Amount to subtract
Returns:	True if reference count is 0, otherwise False
Return type:	bool
Raises:	UnderflowException – refcount underflow

usecount¶

Read/write the reference count

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.usecount
1
>>> ref.inc()
>>> ref.usecount
2
>>> ref.usecount = 4
>>> ref.usecount
4

Returns:	Current reference count
Return type:	int

value¶

Reference count protected value

Allows access to the protected value as long as a valid reference count is held.

>>> from refcount import RefcountedValue
>>> ref = RefcountedValue(value=True)
>>> ref.value
True
>>> ref.dec()
>>> ref.value # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
NameError: Value referenced with no reference count

Returns:	value
Raises:	NameError – Value referenced with no reference count

class refcount.Refcounter(usecount=1, acquire=None, release=None)¶

Bases: object

Provides a reference counter with an optional release callback that is triggered when the last user drops off.

add(value)¶

Add to a reference count

If the reference count becomes higher than 0, the acquire callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.add(2)
>>> ref.usecount
3

Parameters:	value (int) – Amount to add

add_not_zero(value)¶

Add to a reference count unless it is 0

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.dec()
>>> ref.usecount
0
>>> ref.add_not_zero(2)
False

Parameters:	value (int) – Amount to add
Returns:	False if refcount is 0, True otherwise

dec()¶

Decrement reference count by 1

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> def refcount_released():
...     print('no more users')
>>> ref = Refcounter(release=refcount_released)
>>> ref.inc()
>>> ref.dec()
>>> ref.dec()
no more users

Raises:	UnderflowException – refcount underflow

dec_and_test()¶

Decrement reference count and test if the reference count is 0

This can be used by code that wishes to implement a cleanup path triggered only when the reference count drops to 0.

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> if ref.dec_and_test():
...     print('reference count is now 0')
reference count is now 0

Returns:	True if reference count is 0, otherwise False
Return type:	bool
Raises:	UnderflowException – refcount underflow

inc()¶

Increment reference count by 1

If the reference count becomes higher than 0, the acquire callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.usecount
1
>>> ref.inc()
>>> ref.usecount
2

inc_not_zero()¶

Increment a reference by 1 unless it is 0

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.dec()
>>> ref.usecount
0
>>> ref.inc_not_zero()
False

Returns:	False if refcount is 0, True otherwise

sub(value)¶

Subtract from a reference count

>>> from refcount import Refcounter
>>> ref = Refcounter(usecount=3)
>>> ref.usecount
3
>>> ref.sub(2)
>>> ref.usecount
1

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

Parameters:	value (int) – Amount to subtract
Raises:	UnderflowException – refcount underflow

sub_and_test(value)¶

Subtract reference count and test if the reference count is 0

This can be used by code that wishes to implement a cleanup path triggered only when the reference count drops to 0.

If the reference count drops to 0, the release callback (if provided) will be automatically triggered.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.inc()
>>> if ref.sub_and_test(2):
...     print('reference count is now 0')
reference count is now 0

Parameters:	value (int) – Amount to subtract
Returns:	True if reference count is 0, otherwise False
Return type:	bool
Raises:	UnderflowException – refcount underflow

usecount¶

Read/write the reference count

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.usecount
1
>>> ref.inc()
>>> ref.usecount
2
>>> ref.usecount = 4
>>> ref.usecount
4

Returns:	Current reference count
Return type:	int

exception refcount.UnderflowException¶

Bases: Exception

Reference counter underflow exception, raised on counter underflow.

>>> from refcount import Refcounter
>>> ref = Refcounter()
>>> ref.dec()
>>> ref.usecount
0
>>> ref.dec() # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
refcount.UnderflowException: refcount underflow

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

APIs¶

refcount module¶

refcount¶

`refcount`¶