_GFX_share / _GFX_unshare

Adds or removes a host memory area to the set of shared memory areas. This topic only applies to Intel® 64 and IA-32 architectures targeting Intel® Graphics Technology.

Syntax

int _GFX_share(const void * data_ptr, size_t data_size);

int _GFX_unshare(const void * data_ptr);

Parameters

data_ptr

The pointer to the data to be shared or unshared. For _GFX_unshare, the pointer value should match a pointer value previous passed to _GFX_share, or an error code is returned.

data_size

The size of the data to be shared or unshared.

Description

This function adds or removes a host memory area to the set of shared memory areas. The allocation of the internal buffer objects covering all shared areas can be performed lazily. For example, in a subsequent call to _GFX_offload, when the target view of the shared data is really needed.

You should call _GFX_unshare for each area previously shared using _GFX_share, or the system does not release the internal buffer, or execute other operations to stop sharing the memory, which may eventually result in system performance degradation or other resource constraints.

The runtime handles minimizing the number of internal buffer objects and the number of times the shared buffers are recreated. In many cases, a single internal buffer object covers many areas defined by _GFX_share. However, there are system restrictions on co-allocating disjoint shared areas on the same shared buffer, so you should minimize the number of disjoint shared areas, such as large shared areas covering multiple objects.

The function is thread safe, meaning it can be accessed from different host threads without extra synchronization effort on your part.

Note

The set of shared areas is global across all threads.

Return Values

GFX_SUCCESS (0)

The function succeeded.

A non-zero error code

An error has occurred. Use the function _GFX_get_last_error() to get the specific error code. Additonally, gfx_rt.h defines various error status values.

For more complete information about compiler optimizations, see our Optimization Notice.