StreamCallback

#include <poplar/StreamCallback.hpp>

namespace poplar

Poplar classes and functions.

class LegacyStreamCallback : public poplar::StreamCallback 

#include <StreamCallback.hpp>

Convenience StreamCallback specialization for implementations that do not support prefetch/complete operations.

Public Functions

inline virtual Result prefetch(void*) final override: Not available in legacy streams.

inline virtual void invalidatePrefetched() final override: Not available in legacy streams.

inline virtual void complete() final override: Not available in legacy streams.

class ResumableStreamCallback : public poplar::StreamCallback 

#include <StreamCallback.hpp>

Expands StreamCallback API with functions that prevent further progress.

Useful when there are dependencies or conditions between callbacks that prevent progress within the callback function.

Public Functions

ResumableStreamCallback()

~ResumableStreamCallback()

void notify()

Schedules the callback task back to execution.

Continues execution from the last point where wait() was called.

bool isAwaiting() const: Returns whether the callback task is waiting to be notified.

Protected Functions

void wait()

Calling this function will suspend the execution of the current callback.

Should only be called from this.

Private Members

SSOPointer<ConditionVar> conditionVar

class StreamCallback

#include <StreamCallback.hpp>

Interface used during stream copies to produce/consume the data being exchanged between the host and the device.

In regular stream copies, fetch() and complete() are called as a result of the device requesting the data transfer.

If the following engine options are set, prefetch() will be called after an ongoing host-to-device transfer of the same stream completes:

exchange.streamBufferOverlap=none
exchange.enablePrefetch=true

Subclassed by poplar::LegacyStreamCallback, poplar::ResumableStreamCallback

Public Types

enum Result

Values:

enumerator Success

enumerator NotAvailable

Public Functions

virtual ~StreamCallback() = default

virtual Result prefetch(void *p) = 0

Callback function to fill the host buffer (host-to-device streams only).

This function is called speculatively, this means it might still be called even if no additional copies for this stream exist for the remaining execution of the program.

The following situations are possible during the invocation:

There is more data available for consumption (A)
Data is temporarily not available during the time this function is called (B)
The stream reached the end and so no more data is available (C)

The return value indicates if the invocation resulted in the buffer being successfully filled. In the first case (A), the function shall return Result::Success. A call to complete() will follow if the program ends up transferring the data. Otherwise (scenarios B and C), it must return Result::NotAvailable. Calls to fetch() and then complete() will follow if the transfer takes place.

Note that when using a buffered data stream (see Graph::addHostToDeviceFIFO(), bufferingDepth option) there can be multiple calls to prefetch() before a corresponding complete() is called. In some circumstances prefetched data is invalidated and not read, and therefore will have no corresponding complete(), this is notified with invalidatePrefetched().

Parameters: p – Location of the buffer. It will only be valid for the duration of the function.
Returns: Result::Success if the function was able to fill the buffer with data, or Result::NotAvailable otherwise.

virtual void complete() = 0

Notifies that the data involved in the last prefetch/fetch invocation is used by the device.

It usually means that a speculative read was a hit, and the callback can move on to the next piece of input.

inline virtual void invalidatePrefetched(): Notifies when the engine will reset this stream (invalidating any prefetched data which has not been read).

virtual void fetch(void*) = 0

Callback function to fill the host buffer.

This function is called as a result of a stream copy, unless the last prefetch() invocation was successful.

It must always fill the buffer with more data and it is followed by a call to complete().

class StreamCallbackHandle

#include <StreamCallback.hpp>

Wrapper for StreamCallback instances.

Provides backwards compatibility with C++ lambda expressions and std::function instances.

Public Functions

template<class CallbackImpl, typename = typename std::enable_if<std::is_base_of<StreamCallback, CallbackImpl>::value>::type> inline StreamCallbackHandle(std::unique_ptr<CallbackImpl> f)

Constructs a handle from an instance of a stream callback implementation.

This constructor only participates in overload resolution if CallbackImpl is derived from poplar::StreamCallback (in other words, it is an implementation of the callback interface).

template<class F, typename = typename std::enable_if<traits::is_callback<F>::value>::type> inline StreamCallbackHandle(F &&f)

Constructs a handle from a callable instance.

This constructor only participates in overload resolution if F satisfies the requirements of a Function Object. It transforms f into a LegacyStreamCallback implementation.