TSDuck v3.38-3696
MPEG Transport Stream Toolkit
No Matches
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__()

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.


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

◆ _setNative()

tsduck.NativeObject._setNative (   self,

Set the native object.

This is typically done by subclass constructors.

objAddress of the C++ native object to store.

◆ _getNative()

tsduck.NativeObject._getNative (   self)

Get the native object.

This is typically used by subclasses.

Address of the C++ native object.

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