tsduck.NativeObject Class Reference

This base class is derived by all TSDuck classes which are backed by a C++ object. More...

Inheritance diagram for tsduck.NativeObject:

Public Member Functions
	__init__ (self)
	Constructor for subclasses.
	delete (self)
	Explicitly free the underlying C++ object.

Protected Member Functions
	_getNative (self)
	Get the native object.
	_setNative (self, obj)
	Set the native object.

Detailed Description

This base class is derived by all TSDuck classes which are backed by a C++ object.

There is an inherent problem when garbage-collected languages such as Python are interfaced with languages using explicit memory management. When a Python class encapsulates a native C++ object of the corresponding C++ class, when should the C++ object be deleted? This is a problem which has been discussed many times on the Internet and the answer is disappointing: there is no good solution.

1. A naive approach would be to override del(self) and perform the C++ deallocation here. It is well known that del() creates more issues than it solves. Specifically, we cannot guarantee the order of finalization of objects, which could lead to crashes when C++ objects reference each other is a predetermined order.
2. Never delete C++ objects and let them accumulate. This can be acceptable if a guaranteed maximum number of C++ objects are allocated during the life of the application and the corresponding memory usage is acceptable.
3. Expose a public method in all Python classes which deletes, frees, deallocates, you name it, the encapsulated C++ object. It is then the responsibility of the application to call this method on time. This is counter-intuitive to both Python and C++ programmers but this is the price to pay when you want to use them together.

In the Python TSDuck bindings, all classes which encapsulate a C++ object derive from the base class NativeObject which provides the delete() method to explicitly delete the C++ object. In practice, users have the choice between solutions 2 or 3.

Constructor & Destructor Documentation

__init__()

tsduck.NativeObject.__init__

(

self

)

Constructor for subclasses.

Reimplemented in tsduck.Report, tsduck.NullReport, tsduck.StdErrReport, tsduck.AbstractPluginEventHandler, tsduck.PluginEventHandlerRegistry, tsduck.SectionFile, tsduck.DuckContext, tsduck.TSProcessor, tsduck.InputSwitcher, tsduck.SystemMonitor, tsduck.AbstractSyncReport, tsduck.AbstractAsyncReport, and tsduck.AsyncReport.

Member Function Documentation

delete()

tsduck.NativeObject.delete

(

self

)

Explicitly free the underlying C++ object.

After this call, the object becomes unusable. Most usages are unpredictable but most likely will do nothing.

Returns

None.

Reimplemented in tsduck.AsyncReport, tsduck.DuckContext, tsduck.AbstractPluginEventHandler, tsduck.SectionFile, tsduck.SystemMonitor, tsduck.TSProcessor, and tsduck.InputSwitcher.

_setNative()

tsduck.NativeObject._setNative (   self,   obj  )

protected

Set the native object.

This is typically done by subclass constructors.

Parameters

obj	Address of the C++ native object to store.

_getNative()

tsduck.NativeObject._getNative (   self )

protected

Get the native object.

This is typically used by subclasses.

Returns

Address of the C++ native object.

---

The documentation for this class was generated from the following file:

• tsduck.py