Self-documenting memory ownership semantics tokens

Overview

// macros

#define __dpctl_give
#define __dpctl_keep
#define __dpctl_null
#define __dpctl_take

Detailed Documentation

Macros

#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.

#define __dpctl_keep

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

#define __dpctl_null

The __dpctl_null attribute indicates that a NULL value is returned.

#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.