retain_event

Increments the event reference count.

void retain_event ( clk_event_t  event )

Description

Increments the event reference count. event must be an event returned by enqueue_kernel or enqueue_marker or a user event.

Notes

Events can be used to identify commands enqueued to a command-queue from the host. These events created by the OpenCL runtime can only be used on the host i.e. as events passed in event_wait_list argument to various clEnqueue APIs or runtime APIs that take events as arguments such as clRetainEvent, clReleaseEvent, clGetEventProfilingInfo.

Similarly, events can be used to identify commands enqueued to a device queue (from a kernel). These event objects s cannot be passed to the host or used by OpenCL runtime APIs such as the clEnqueueAPIs or runtime APIs that take event arguments.

clRetainEvent and clReleaseEvent will return CL_INVALID_OPERATION if event specified is an event that refers to any kernel enqueued to a device queue using enqueue_kernel or or enqueue_marker or is a user event created by create_user_event.

Similarly, clSetUserEventStatus can only be used to set the execution status of events created using clCreateUserEvent. User events created on the device can be set using set_user_event_status built-in function.

Example

The example below shows how events can be used with kernels enqueued to multiple device queues.

extern void barA_kernel(...); extern void barB_kernel(...); kernel void foo(queue_t q0, queue q1, ...) { ... clk_event_t evt0; // enqueue kernel to queue q0 enqueue_kernel(q0, CLK_ENQUEUE_FLAGS_NO_WAIT, ndrange_A, 0, NULL, &evt0, ^{barA_kernel(...);} ); // enqueue kernel to queue q1 enqueue_kernel(q1, CLK_ENQUEUE_FLAGS_NO_WAIT, ndrange_B, 1, &evt0, NULL, ^{barB_kernel(...);} ); // release event evt0. This will get released // after barA_kernel enqueued in queue q0 has finished // execution and barB_kernel enqueued in queue q1 and // waits for evt0 is submitted for execution i.e. wait // for evt0 is satisfied. release_event(evt0); }

The example below shows how the marker command can be used with kernels enqueued to a device queue.

kernel void foo(queue_t q, ...) { ... clk_event_t marker_event; clk_event_t events[2]; enqueue_kernel(q, CLK_ENQUEUE_FLAGS_NO_WAIT, ndrange, 0, NULL, &events[0], ^{barA_kernel(...);} ); enqueue_kernel(q, CLK_ENQUEUE_FLAGS_NO_WAIT, ndrange, 0, NULL, &events[1], ^{barB_kernel(...);} ); // barA_kernel and barB_kernel can be executed // out of order. we need to wait for both these // kernels to finish execution before barC_kernel // starts execution so we enqueue a marker command and // then enqueue barC_kernel that waits on the event // associated with the marker. enqueue_marker(q, 2, events, &marker_event); enqueue_kernel(q, CLK_ENQUEUE_FLAGS_NO_WAIT, 1, &marker_event, NULL, ^{barC_kernel(...);} ); release_event(events[0]; release_event(events[1]); release_event(marker_event); }

Specification

OpenCL Specification

Also see

Event Functions

Copyright © 2007-2013 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.