.. index:: pair: group; Self-documenting memory ownership semantics tokens
.. _doxid-d2/d43/group___memory_semantics:

Self-documenting memory ownership semantics tokens
==================================================

.. toctree::
	:hidden:

Overview
~~~~~~~~




.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// macros

	#define :ref:`__dpctl_give<doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452>`
	#define :ref:`__dpctl_keep<doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7>`
	#define :ref:`__dpctl_null<doxid-d2/d43/group___memory_semantics_1ga8afac1975b8353a1bd54ac25b2572d04>`
	#define :ref:`__dpctl_take<doxid-d2/d43/group___memory_semantics_1ga17fe5722d78d8ce138ca952889d07bc6>`

.. _details-d2/d43/group___memory_semantics:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~



Macros
------

.. index:: pair: define; __dpctl_give
.. _doxid-d2/d43/group___memory_semantics_1ga836492a42cdfef6419378dbf8d81f452:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define __dpctl_give

The \__dpctl_give attribute indicates that a new object is returned and the caller now owns the object.

The \__dpctl_give attribute informs a user that the function is allocating a new object and returning it to the user. The user now owns the object and to free the object, he/she should make sure to use it exactly once as a value for a \__dpctl_take argument. However, the user is free to use the object as he/she likes as a value to \__dpctl_keep arguments.

.. index:: pair: define; __dpctl_keep
.. _doxid-d2/d43/group___memory_semantics_1gadd48a0161309931574aed2025a16ade7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define __dpctl_keep

The \__dpctl_keep attribute indicates that the function only uses the object and does not destroy it before returning.

.. index:: pair: define; __dpctl_null
.. _doxid-d2/d43/group___memory_semantics_1ga8afac1975b8353a1bd54ac25b2572d04:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define __dpctl_null

The \__dpctl_null attribute indicates that a NULL value is returned.

.. index:: pair: define; __dpctl_take
.. _doxid-d2/d43/group___memory_semantics_1ga17fe5722d78d8ce138ca952889d07bc6:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define __dpctl_take

The \__dpctl_take attribute indicates that the function "takes" over the ownership of the object and the user must not use the object as an argument to another function.

The \__dpctl_take attribute means that the function destroys it before the function returns, and the caller must not use the object again in any other function. If the pointer annotated with \__dpctl_take is NULL then it is treated as an error, since it may prevent the normal behavior of the function.