Plugin class for user-implemented layers. More...

#include <NvInferRuntimePlugin.h>

Inheritance diagram for nvinfer1::IPluginV2:

Public Member Functions
virtual int32_t	getTensorRTVersion () const noexcept
	Return the API version with which this plugin was built. More...

virtual AsciiChar const *	getPluginType () const noexcept=0
	Return the plugin type. Should match the plugin name returned by the corresponding plugin creator. More...

virtual AsciiChar const *	getPluginVersion () const noexcept=0
	Return the plugin version. Should match the plugin version returned by the corresponding plugin creator. More...

virtual int32_t	getNbOutputs () const noexcept=0
	Get the number of outputs from the layer. More...

virtual Dims	getOutputDimensions (int32_t index, Dims const *inputs, int32_t nbInputDims) noexcept=0
	Get the dimension of an output tensor. More...

virtual bool	supportsFormat (DataType type, PluginFormat format) const noexcept=0
	Check format support. More...

virtual void	configureWithFormat (Dims const inputDims, int32_t nbInputs, Dims const outputDims, int32_t nbOutputs, DataType type, PluginFormat format, int32_t maxBatchSize) noexcept=0
	Configure the layer. More...

virtual int32_t	initialize () noexcept=0
	Initialize the layer for execution. This is called when the engine is created. More...

virtual void	terminate () noexcept=0
	Release resources acquired during plugin layer initialization. This is called when the engine is destroyed. More...

virtual size_t	getWorkspaceSize (int32_t maxBatchSize) const noexcept=0
	Find the workspace size required by the layer. More...

virtual int32_t	enqueue (int32_t batchSize, void const const inputs, void const outputs, void *workspace, cudaStream_t stream) noexcept=0
	Execute the layer. More...

virtual size_t	getSerializationSize () const noexcept=0
	Find the size of the serialization buffer required to store the plugin configuration in a binary file. More...

virtual void	serialize (void *buffer) const noexcept=0
	Serialize the layer. More...

virtual void	destroy () noexcept=0
	Destroy the plugin object. This will be called when the network, builder or engine is destroyed. More...

virtual IPluginV2 *	clone () const noexcept=0
	Clone the plugin object. This copies over internal plugin parameters and returns a new plugin object with these parameters. More...

virtual void	setPluginNamespace (AsciiChar const *pluginNamespace) noexcept=0
	Set the namespace that this plugin object belongs to. Ideally, all plugin objects from the same plugin library must have the same namespace. More...

virtual AsciiChar const *	getPluginNamespace () const noexcept=0
	Return the namespace of the plugin object. More...

Detailed Description

Plugin class for user-implemented layers.

Plugins are a mechanism for applications to implement custom layers. When combined with IPluginCreator it provides a mechanism to register plugins and look up the Plugin Registry during de-serialization.

See also: IPluginCreator; IPluginRegistry

Deprecated:: Deprecated in TensorRT 8.5. Implement IPluginV2DynamicExt or IPluginV2IOExt depending on your requirement.

Member Function Documentation

◆ clone()

virtual IPluginV2 * nvinfer1::IPluginV2::clone ( ) const

pure virtualnoexcept

Clone the plugin object. This copies over internal plugin parameters and returns a new plugin object with these parameters.

The TensorRT runtime calls clone() to clone the plugin when an execution context is created for an engine, after the engine has been created. The runtime does not call initialize() on the cloned plugin, so the cloned plugin must be created in an initialized state.

Returns: A cloned plugin object in an initialized state with the same parameters as the current object. nullptr must be returned if the cloning fails, e.g. because of resource exhaustion.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin or when creating multiple execution contexts.

Implemented in nvinfer1::IPluginV2DynamicExt, and nvinfer1::IPluginV2Ext.

◆ configureWithFormat()

virtual void nvinfer1::IPluginV2::configureWithFormat	(	Dims const *	inputDims,
		int32_t	nbInputs,
		Dims const *	outputDims,
		int32_t	nbOutputs,
		DataType	type,
		PluginFormat	format,
		int32_t	maxBatchSize
	)

pure virtualnoexcept

Configure the layer.

This function is called by the builder prior to initialize(). It provides an opportunity for the layer to make algorithm choices on the basis of its weights, dimensions, and maximum batch size.

Parameters

inputDims	The input tensor dimensions. Will be the start address of a Dims array of length nbInputs.
nbInputs	The number of inputs. Will be a non-negative integer.
outputDims	The output tensor dimensions. Will be the start address of a Dims array of length nbOutputs.
nbOutputs	The number of outputs. Will be a positive integer identical to the return value of getNbOutputs().
type	The data type selected for the engine.
format	The format selected for the engine.
maxBatchSize	The maximum batch size. Will be a positive integer.

The dimensions passed here do not include the outermost batch size (i.e. for 2-D image networks, they will be 3-dimensional CHW dimensions).

Warning: for the format field, the values PluginFormat::kCHW4, PluginFormat::kCHW16, and PluginFormat::kCHW32 will not be passed in, this is to keep backward compatibility with TensorRT 5.x series. Use PluginV2IOExt or PluginV2DynamicExt for other PluginFormats.; DataType:kBOOL and DataType::kUINT8 are not supported.

See also: clone()

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin. However, TensorRT will not call this method from two threads simultaneously on a given clone of a plugin.

Implemented in nvinfer1::IPluginV2Ext.

◆ destroy()

virtual void nvinfer1::IPluginV2::destroy ( )

pure virtualnoexcept

Destroy the plugin object. This will be called when the network, builder or engine is destroyed.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ enqueue()

virtual int32_t nvinfer1::IPluginV2::enqueue	(	int32_t	batchSize,
		void const const	inputs,
		void const	outputs,
		void *	workspace,
		cudaStream_t	stream
	)

pure virtualnoexcept

Execute the layer.

Parameters

batchSize	The number of inputs in the batch.
inputs	The memory for the input tensors. Will be an array of device addresses corresponding to input tensors of length nbInputs, where nbInputs is the second parameter passed to configureWithFormat(). The i-th input tensor will have the dimensions inputDims[i], where inputDims is the first parameter that was passed to configureWithFormat().
outputs	The memory for the output tensors. Will be an array of device addresses corresponding to output tensors of length getNbOutputs().
workspace	Workspace for execution. Will be the start address of a device buffer whose length will be at least getWorkspaceSize(batchSize).
stream	The stream in which to execute the kernels. This will be a valid CUDA stream.

Returns: 0 for success, else non-zero (which will cause engine termination).

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when multiple execution contexts are used during runtime.

◆ getNbOutputs()

virtual int32_t nvinfer1::IPluginV2::getNbOutputs ( ) const

pure virtualnoexcept

Get the number of outputs from the layer.

Returns: The number of outputs, which is a positive integer.

This function is called by the implementations of INetworkDefinition and IBuilder. In particular, it is called prior to any call to initialize().

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ getOutputDimensions()

virtual Dims nvinfer1::IPluginV2::getOutputDimensions	(	int32_t	index,
		Dims const *	inputs,
		int32_t	nbInputDims
	)

pure virtualnoexcept

Get the dimension of an output tensor.

Parameters

index	The index of the output tensor. Will lie in the valid range (between 0 and getNbOutputs()-1 inclusive).
inputs	The input tensor dimensions. Will be the start address of a Dims array of length nbInputDims.
nbInputDims	The number of input tensors. Will be a non-negative integer.

Returns: The output tensor dimensions if the index is in the valid range. An invalid value of Dims{-1, {}} must be returned if the index is not in the valid range.

This function is called by the implementations of INetworkDefinition and IBuilder. In particular, it is called prior to any call to initialize().

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

Note: In any non-IPluginV2DynamicExt plugin, batch size must not be included in the returned dimensions, even if the plugin is expected to be run in a network with explicit batch mode enabled. Please see the TensorRT Developer Guide for more details on how plugin inputs and outputs behave.

◆ getPluginNamespace()

virtual AsciiChar const * nvinfer1::IPluginV2::getPluginNamespace ( ) const

pure virtualnoexcept

Return the namespace of the plugin object.

Returns: The namespace string that was passed to setPluginNamespace(), possibly after truncation to 1024 bytes if a longer string was passed. An empty string must be returned as default value.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ getPluginType()

virtual AsciiChar const * nvinfer1::IPluginV2::getPluginType ( ) const

pure virtualnoexcept

Return the plugin type. Should match the plugin name returned by the corresponding plugin creator.

See also: IPluginCreator::getPluginName()

Warning: The string returned must be NULL-terminated and have a length of 1024 bytes or less including the NULL terminator.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ getPluginVersion()

virtual AsciiChar const * nvinfer1::IPluginV2::getPluginVersion ( ) const

pure virtualnoexcept

Return the plugin version. Should match the plugin version returned by the corresponding plugin creator.

See also: IPluginCreator::getPluginVersion()

Warning: The string returned must be NULL-terminated and have a length of 1024 bytes or less including the NULL terminator.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ getSerializationSize()

virtual size_t nvinfer1::IPluginV2::getSerializationSize ( ) const

pure virtualnoexcept

Find the size of the serialization buffer required to store the plugin configuration in a binary file.

Returns: The size of the serialization buffer in bytes.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ getTensorRTVersion()

virtual int32_t nvinfer1::IPluginV2::getTensorRTVersion ( ) const

inlinevirtualnoexcept

Return the API version with which this plugin was built.

Do not override this method as it is used by the TensorRT library to maintain backwards-compatibility with plugins.

Returns: The TensorRT version in the format (major * 100 + minor) * 100 + patch.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, the implementation provided here is safe to call from any thread.

Reimplemented in nvinfer1::IPluginV2DynamicExt, nvinfer1::IPluginV2Ext, and nvinfer1::IPluginV2IOExt.

◆ getWorkspaceSize()

virtual size_t nvinfer1::IPluginV2::getWorkspaceSize ( int32_t maxBatchSize ) const

pure virtualnoexcept

Find the workspace size required by the layer.

This function is called during engine startup, after initialize(). The workspace size returned must be sufficient for any batch size up to the maximum.

Parameters

maxBatchSize The maximum batch size, which will be a positive integer.

Returns: The workspace size in bytes, i.e. the device memory size that the plugin requires for its internal computations.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin. However, TensorRT will not call this method from two threads simultaneously on a given clone of a plugin.

◆ initialize()

virtual int32_t nvinfer1::IPluginV2::initialize ( )

pure virtualnoexcept

Initialize the layer for execution. This is called when the engine is created.

Returns: 0 for success, else non-zero (which will cause engine termination).

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin or when using multiple execution contexts using this plugin.

◆ serialize()

virtual void nvinfer1::IPluginV2::serialize ( void * buffer ) const

pure virtualnoexcept

Serialize the layer.

Parameters

buffer A pointer to a host buffer to serialize data. Size of buffer will be at least as large as the value returned by getSerializationSize.

See also: getSerializationSize()

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ setPluginNamespace()

virtual void nvinfer1::IPluginV2::setPluginNamespace ( AsciiChar const * pluginNamespace )

pure virtualnoexcept

Set the namespace that this plugin object belongs to. Ideally, all plugin objects from the same plugin library must have the same namespace.

Parameters

pluginNamespace The namespace for the plugin object.

Warning: The string pluginNamespace will be NULL-terminated and have a length of 1024 bytes or less including the NULL terminator.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ supportsFormat()

virtual bool nvinfer1::IPluginV2::supportsFormat	(	DataType	type,
		PluginFormat	format
	)		const

pure virtualnoexcept

Check format support.

Parameters

type	DataType requested.
format	PluginFormat requested.

Returns: true if the plugin supports the type-format combination.

This function is called by the implementations of INetworkDefinition, IBuilder, and safe::ICudaEngine/ICudaEngine. In particular, it is called when creating an engine and when deserializing an engine.

Warning: for the format field, the values PluginFormat::kCHW4, PluginFormat::kCHW16, and PluginFormat::kCHW32 will not be passed in, this is to keep backward compatibility with TensorRT 5.x series. Use PluginV2IOExt or PluginV2DynamicExt for other PluginFormats.; DataType:kBOOL and DataType::kUINT8 are not supported.

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin.

◆ terminate()

virtual void nvinfer1::IPluginV2::terminate ( )

pure virtualnoexcept

Release resources acquired during plugin layer initialization. This is called when the engine is destroyed.

See also: initialize()

Usage considerations

Allowed context for the API call
- Thread-safe: Yes, this method is required to be thread-safe and may be called from multiple threads when building networks on multiple devices sharing the same plugin or when using multiple execution contexts using this plugin. However, TensorRT will not call this method from two threads simultaneously on a given clone of a plugin.

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

NvInferRuntimePlugin.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ clone()

◆ configureWithFormat()

◆ destroy()

◆ enqueue()

◆ getNbOutputs()

◆ getOutputDimensions()

◆ getPluginNamespace()

◆ getPluginType()

◆ getPluginVersion()

◆ getSerializationSize()

◆ getTensorRTVersion()

◆ getWorkspaceSize()

◆ initialize()

◆ serialize()

◆ setPluginNamespace()

◆ supportsFormat()

◆ terminate()