Struct ocl::async::FutureGuard
source · pub struct FutureGuard<V, G>where
G: OrderGuard<V>,{ /* private fields */ }
Expand description
A future that resolves to a read or write guard after ensuring that the data being guarded is appropriately locked during the execution of an OpenCL command.
- Waits until both an exclusive data lock can be obtained and all prerequisite OpenCL commands have completed.
- Triggers an OpenCL command, remaining locked while the command executes.
- Returns a guard which provides exclusive (write) or shared (read) access to the locked data.
Implementations§
source§impl<V, G> FutureGuard<V, G>where
G: OrderGuard<V>,
impl<V, G> FutureGuard<V, G>where
G: OrderGuard<V>,
sourcepub fn set_lock_wait_events<L: Into<EventList>>(&mut self, wait_events: L)
pub fn set_lock_wait_events<L: Into<EventList>>(&mut self, wait_events: L)
Sets an event wait list.
Setting a wait list will cause this FutureGuard
to wait until
contained events have their status set to complete before obtaining a
lock on the guarded internal value.
[UNSTABLE]: This method may be renamed or otherwise changed at any time.
sourcepub fn ewait_lock<L: Into<EventList>>(self, wait_events: L) -> FutureGuard<V, G>
pub fn ewait_lock<L: Into<EventList>>(self, wait_events: L) -> FutureGuard<V, G>
Sets an event wait list.
See ::set_lock_wait_events
.
[UNSTABLE]: This method may be renamed or otherwise changed at any time.
sourcepub fn create_lock_event<C: ClContextPtr>(
&mut self,
context: C
) -> OclResult<&Event>
pub fn create_lock_event<C: ClContextPtr>( &mut self, context: C ) -> OclResult<&Event>
Creates an event which will be triggered when a lock is obtained on the guarded internal value.
The returned event can be added to the wait list of subsequent OpenCL commands with the expectation that when all preceding futures are complete, the event will automatically be ‘triggered’ by having its status set to complete, causing those commands to execute. This can be used to inject host side code in amongst OpenCL commands without thread blocking or extra delays of any kind.
sourcepub fn enew_lock<C, En>(self, context: C, enew: En) -> FutureGuard<V, G>where
C: ClContextPtr,
En: ClNullEventPtr,
pub fn enew_lock<C, En>(self, context: C, enew: En) -> FutureGuard<V, G>where
C: ClContextPtr,
En: ClNullEventPtr,
Creates an event which will be triggered when a lock is obtained on the guarded internal value.
enew
must be an empty (null) event or event list.
See ::create_lock_event
§Panics
Panics if there is an error creating the lock event.
[UNSTABLE]: This method may be renamed or otherwise changed at any time.
sourcepub fn set_command_wait_event(&mut self, command_event: Event)
pub fn set_command_wait_event(&mut self, command_event: Event)
Sets a command completion wait event.
command_event
must be an event created by enqueuing an OpenCL
command which interacts (reads/writes) with the data associated with
this FutureGuard
.
If the command completion event is specified, this FutureGuard
will
“suffix” itself with an additional future that will wait until the
command completes before resolving.
Not specifying a command completion event will cause this
FutureGuard
to resolve into an OrderGuard
immediately after the
lock is obtained (indicated by the optionally created lock event).
[UNSTABLE]: This method may be renamed or otherwise changed at any time.
sourcepub fn ewait_command(self, command_event: Event) -> FutureGuard<V, G>
pub fn ewait_command(self, command_event: Event) -> FutureGuard<V, G>
Sets a command completion wait event.
See ::set_command_wait_event
.
[UNSTABLE]: This method may be renamed or otherwise changed at any time.
sourcepub fn create_release_event<C: ClContextPtr>(
&mut self,
context: C
) -> OclResult<&Event>
pub fn create_release_event<C: ClContextPtr>( &mut self, context: C ) -> OclResult<&Event>
Creates an event which will be triggered after this future resolves
and the ensuing OrderGuard
is dropped or manually released.
The returned event can be added to the wait list of subsequent OpenCL commands with the expectation that when all preceding futures are complete, the event will automatically be ‘triggered’ by having its status set to complete, causing those commands to execute. This can be used to inject host side code in amongst OpenCL commands without thread blocking or extra delays of any kind.
sourcepub fn enew_release<C, En>(self, context: C, enew: En) -> FutureGuard<V, G>where
C: ClContextPtr,
En: ClNullEventPtr,
pub fn enew_release<C, En>(self, context: C, enew: En) -> FutureGuard<V, G>where
C: ClContextPtr,
En: ClNullEventPtr,
Creates an event which will be triggered after this future resolves
and the ensuing OrderGuard
is dropped or manually released.
enew
must be an empty (null) event or event list.
See ::create_release_event
.
§Panics
Panics if there is an error creating the release event.
[UNSTABLE]: This method may be renamed or otherwise changed at any time.
sourcepub fn lock_event(&self) -> Option<&Event>
pub fn lock_event(&self) -> Option<&Event>
Returns a reference to the event previously created with
::create_lock_event
or ::enew_lock
which will trigger (be
completed) when the wait events are complete and the lock is locked.
sourcepub fn release_event(&self) -> Option<&Event>
pub fn release_event(&self) -> Option<&Event>
Returns a reference to the event previously created with
::create_release_event
or ::enew_release
which will trigger (be
completed) when a lock is obtained on the guarded internal value.
sourcepub fn wait(self) -> OclResult<G>
pub fn wait(self) -> OclResult<G>
Blocks the current thread until the OpenCL command is complete and an appropriate lock can be obtained on the underlying data.
sourcepub fn as_ptr(&self) -> *const V
pub fn as_ptr(&self) -> *const V
Returns a mutable pointer to the data contained within the internal value, bypassing all locks and protections.
§Panics
This future must not have already resolved into a guard.
sourcepub fn as_mut_ptr(&self) -> *mut V
pub fn as_mut_ptr(&self) -> *mut V
Returns a mutable pointer to the data contained within the internal value, bypassing all locks and protections.
§Panics
This future must not have already resolved into a guard.
sourcepub fn order_lock(&self) -> &OrderLock<V>
pub fn order_lock(&self) -> &OrderLock<V>
Returns a reference to the OrderLock
used to create this future.
source§impl<V> FutureGuard<V, ReadGuard<V>>
impl<V> FutureGuard<V, ReadGuard<V>>
pub fn upgrade_after_command(self) -> FutureGuard<V, WriteGuard<V>>
Trait Implementations§
source§impl<V: Debug, G> Debug for FutureGuard<V, G>where
G: OrderGuard<V> + Debug,
impl<V: Debug, G> Debug for FutureGuard<V, G>where
G: OrderGuard<V> + Debug,
source§impl<V, G> Drop for FutureGuard<V, G>where
G: OrderGuard<V>,
impl<V, G> Drop for FutureGuard<V, G>where
G: OrderGuard<V>,
source§fn drop(&mut self)
fn drop(&mut self)
Drops this FutureGuard.
Blocks the current thread until the command associated with this
FutureGuard
(represented by the command completion event)
completes. This ensures that the underlying value is not dropped
before the command completes (which would cause obvious problems).
§future_guard_drop_panic
Feature
If the future_guard_drop_panic
feature is enabled, dropping a
FutureGuard
before it is polled will cause a panic.
source§impl<V, G> Future for FutureGuard<V, G>where
G: OrderGuard<V>,
impl<V, G> Future for FutureGuard<V, G>where
G: OrderGuard<V>,
§type Error = Error
type Error = Error
source§fn poll(&mut self) -> Poll<Self::Item, Self::Error>
fn poll(&mut self) -> Poll<Self::Item, Self::Error>
source§fn wait(self) -> Result<Self::Item, Self::Error>where
Self: Sized,
fn wait(self) -> Result<Self::Item, Self::Error>where
Self: Sized,
source§fn map<F, U>(self, f: F) -> Map<Self, F>
fn map<F, U>(self, f: F) -> Map<Self, F>
source§fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
source§fn from_err<E>(self) -> FromErr<Self, E>
fn from_err<E>(self) -> FromErr<Self, E>
From
for
this future’s Error
, returning a new future. Read moresource§fn then<F, B>(self, f: F) -> Then<Self, B, F>
fn then<F, B>(self, f: F) -> Then<Self, B, F>
f
. Read moresource§fn and_then<F, B>(self, f: F) -> AndThen<Self, B, F>
fn and_then<F, B>(self, f: F) -> AndThen<Self, B, F>
source§fn or_else<F, B>(self, f: F) -> OrElse<Self, B, F>
fn or_else<F, B>(self, f: F) -> OrElse<Self, B, F>
source§fn select<B>(self, other: B) -> Select<Self, <B as IntoFuture>::Future>
fn select<B>(self, other: B) -> Select<Self, <B as IntoFuture>::Future>
source§fn select2<B>(self, other: B) -> Select2<Self, <B as IntoFuture>::Future>where
B: IntoFuture,
Self: Sized,
fn select2<B>(self, other: B) -> Select2<Self, <B as IntoFuture>::Future>where
B: IntoFuture,
Self: Sized,
source§fn join<B>(self, other: B) -> Join<Self, <B as IntoFuture>::Future>
fn join<B>(self, other: B) -> Join<Self, <B as IntoFuture>::Future>
source§fn join3<B, C>(
self,
b: B,
c: C
) -> Join3<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future>
fn join3<B, C>( self, b: B, c: C ) -> Join3<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future>
join
, but with more futures.source§fn join4<B, C, D>(
self,
b: B,
c: C,
d: D
) -> Join4<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future, <D as IntoFuture>::Future>where
B: IntoFuture<Error = Self::Error>,
C: IntoFuture<Error = Self::Error>,
D: IntoFuture<Error = Self::Error>,
Self: Sized,
fn join4<B, C, D>(
self,
b: B,
c: C,
d: D
) -> Join4<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future, <D as IntoFuture>::Future>where
B: IntoFuture<Error = Self::Error>,
C: IntoFuture<Error = Self::Error>,
D: IntoFuture<Error = Self::Error>,
Self: Sized,
join
, but with more futures.source§fn join5<B, C, D, E>(
self,
b: B,
c: C,
d: D,
e: E
) -> Join5<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future, <D as IntoFuture>::Future, <E as IntoFuture>::Future>where
B: IntoFuture<Error = Self::Error>,
C: IntoFuture<Error = Self::Error>,
D: IntoFuture<Error = Self::Error>,
E: IntoFuture<Error = Self::Error>,
Self: Sized,
fn join5<B, C, D, E>(
self,
b: B,
c: C,
d: D,
e: E
) -> Join5<Self, <B as IntoFuture>::Future, <C as IntoFuture>::Future, <D as IntoFuture>::Future, <E as IntoFuture>::Future>where
B: IntoFuture<Error = Self::Error>,
C: IntoFuture<Error = Self::Error>,
D: IntoFuture<Error = Self::Error>,
E: IntoFuture<Error = Self::Error>,
Self: Sized,
join
, but with more futures.source§fn into_stream(self) -> IntoStream<Self>where
Self: Sized,
fn into_stream(self) -> IntoStream<Self>where
Self: Sized,
source§fn fuse(self) -> Fuse<Self>where
Self: Sized,
fn fuse(self) -> Fuse<Self>where
Self: Sized,
poll
will never again be called once it has
completed. Read more