The new method `ArrayHandle::DeepCopy` had the pattern such that the
data in the `this` array was pushed to the provided destination array.
However, this is the opposite pattern used in the equivalent method in
VTK, which takes the data from the provided array and copies it to
`this` array.
So, swap the pattern to match that of VTK. Also, make the method name
more descriptive by renaming it to `DeepCopyFrom`. Hopefully, users will
read that to mean given the `ArrayHandle`, you copy data from the other
provided `ArrayHandle`.
A recent modification to `ArrayCopy` created a fast path for when
copying arrays of the same type. This fast path just deep copies the
buffers. The issue was that the buffer copy was creating new buffers
instead of updating the existing buffers. The passed in `ArrayHandle`
would get updated to the new buffers, but any other `ArrayHandle`s
sharing those buffers would still have the old versions. That would lead
to unexpected errors in code like this.
```cpp
vtkm::cont::ArrayHandle<T> outArray1;
vtkm::cont::ArrayHandle<T> outArray2 = outArray1;
vtkm::cont::ArrayCopy(inArray, outArray2);
```
If `inArray` was a different type than `outArray2`, then the data for
both `outArray1` and `outArray2` would be updated (which is the expected
behavior for something considered a "pointer"). However, if `inArray`
was the same type as `outArray2`, then the fast path would change
`outArray2` but leave `outArray1` the same.
This behavior has been corrected so that, in this case, the data of
`outArray1` always follows that of `outArray2`.
The old style `ArrayHandle` stored most of its state, including the
data, in the `vtkm::cont::internal::Storage` object (templated to the
type of array). The new style of `ArrayHandle` stores the data itself in
`Buffer` objects, and recent changes to `Buffer` allow metadata to be
stored there, too.
These changes make it pretty unnecessary to hold any state at all in the
`Storage` object. This is good since the sharing of state from one type
of `ArrayHandle` to another (such as by transforming the data), can be
done by just sharing the `Buffer` objects.
To reinforce this behavior, the `Storage` object has been changed to
make it completely stateless. All the methods of `Storage` must be
marked as `static`.
While in the transition between two types of `ArrayHandle`
implementations, we need to declare when an `ArrayHandle` is implemented
with the new style. To consolidate, create a
`VTKM_ARRAY_HANDLE_NEW_STYLE` to override the default `ArrayHandle`
implementation with the `ArrayHandleNewStyle` implementation.
`ArrayHandle::DeepCopy` creates a new `ArrayHandle` of the same type and
deep copies the data into it.
This functionality is similar to `ArrayCopy`. However, it can be used
without having to compile for the device on which the copy happens.
This has no real change in the operation, but it will simplify code as
we convert `ArrayHandle`s to the new type. We will be able to write
simple runtime code rather than complex metaprogramming to determine the
number of buffers to use.
We are moving to deprecate `ArrayHandleVirtual`, so we are removing the
feature where `VariantArrayHandle::CastAndCall` automatically casts to
an `ArrayHandleVirtual` if possible.
The big reason to make this change now (as opposed to later when
`ArrayHandleVirtual` is deprecated) is to improve compile times.
This prevents us from having to compile an extra code path using
`ArrayHandleVirtual`.
`ArrayHandle::PrepareForOutput` often has to reallocate the array to the
specified size. Previously, this allocation was not happening with the
`Token` that is passed to `PrepareForOutput`. If the `ArrayHandle` is
already attached or enqueued for that `Token`, then the allocation would
deadlock.
You can now pass a `Token` object to `Allocate`, which is what
`PrepareForOutput` does.
This makes it clear that it returns true for an invalid array handle.
The previous name implied that it was looking for an ArrayHandle in some
"valid" set, which is the opposite.
Because ArrayHandle currently only supports one device at a time, it is
possible that a `PrepareForInput` might actually need to wait for write
access so that it could move the data between devices. However, we don't
want the `Token` to be attached for writing because that could block
other read operations.
To get around this, add a hack to WaitToWrite to allow it to attach for
reading instead of writing.
An issue that was identified for the thread safety of `ArrayHandle` is
that if several threads are waiting to use an `ArrayHandle`, there might
be an expectation of the order in which the operations happen. For
example, if one thread is modifying the contents of an `ArrayHandle` and
another is reading those results, we would need the first one to start
before the second one.
To solve this, a queue is added to `ArrayHandle` such that when waiting
to read or write an `ArrayHandle` the `Token` has to be at the top of
the queue in addition to other requirements being met.
Additionally, an `Enqueue` method is added to add a `Token` to the queue
without blocking. This allows a control thread to queue the access and
then spawn a thread where the actual work will be done. As long as
everything is enqueued on the main thread, the operations will happen in
the expected order.
The `ArrayHandleStreaming` class stems from an old research project
experimenting with bringing data from an `ArrayHandle` in parts and
overlapping device transfer and execution. It works, but only in very
limited contexts. Thus, it is not actually used today. Plus, the feature
requires global indexing to be permutated throughout the worklet
dispatching classes of VTK-m for no further reason.
Because it is not really used, there are other more promising approaches
on the horizon, and it makes further scheduling improvements difficult,
we are removing this functionality.
Previously, when a ReadPortal or a WritePortal was returned from an
ArrayHandle, it had wrapped in it a Token that was attached to the
ArrayHandle. This Token would prevent other reads and writes from the
ArrayHandle.
This added safety in the form of making sure that the ArrayPortal was
always valid. Unfortunately, it also made deadlocks very easy. They
happened when an ArrayPortal did not leave scope immediately after use
(which is not all that uncommon).
Now, the ArrayPortal no longer locks up the ArrayHandle. Instead, when
an access happens on the ArrayPortal, it checks to make sure that
nothing has happened to the data being accessed. If it has, a fatal
error is reported to the log.
To get a portal to access ArrayHandle values in the control
environment, you now use the ReadPortal and WritePortal methods.
The portals returned are wrapped in an ArrayPortalToken object
so that the data between the portal and the ArrayHandle are
guaranteed to be consistent.
Marked the old versions of PrepareFor* that do not use tokens as
deprecated and moved all of the code to use the new versions that
require a token. This makes the scope of the execution object more
explicit so that it will be kept while in use and can potentially be
reclaimed afterward.
When a single `ArrayHandle` is given to multiple arguments of a worklet
dispatch, the `PrepareFor*` methods will be called multiple times with
the same token. If one of them is a `PrepareForInPlace` or
`PrepareForOutput`, then the two requests will deadlock. To prevent
this, allow the `PrepareFor*` to happen if the same token was used
previously.
Duplicated the new versions of PrepareFor* methods from the basic
ArrayHandle that take a token in addition to the other arguments. The
ArrayHandle attaches itself to the token and will not allow operaitons
that make the returned portal invalid until the token goes out of scope.
Later the old versions will be deprecated.
When it was originally created, it was assumed that the ArrayHandle
class would be used by a single thread. As the use of VTK-m expands,
that is no longer a safe assumption. To ensure that operations on
ArrayHandle happen correctly, add a mutex to the Internals of
ArrayHandle and require all operations on the Internals lock that mutex.
Previously when ApplyPolicyFieldOfType was used in cases where not all
of the types matched not all of the storages, those invalid arrays were
replaced with an ArrayHandleDiscard. This unnecessarily increased the
length of the type names used for the resulting ArrayHandleMultiplexer.
Now, ListTagRemoveIf is used to remove any invalid arrays so that the
resulting ArrayHandleMultiplexer only includes the valid arrays.
IsWritableArrayHandle can now be used directly as `std::true_type` or
`std::false_type` without having to pull the `type` member out of a
dependent namespace.
Previously, IsWriteableArrayHandle just checked to see if an
ArrayHandle's portal has a ValueType of void* because we had coded the
special read-only array handles to have fake portals for writing.
However, we recently removed that because it was more trouble than it
was worth. Now IsWritableArrayHandle checks for the existance of the Set
method. If it does not exist, then the portal is considered read-only.
Also corrected spelling (writeable -> writable).
This adds an ExecutionSignature tag named Device that passes the
DeviceAdapterTag as an argument to the worklet's operator(). This allows
worklets to specialize their code based on the device.
There is a test to ensure that basic VTK-m classes have proper move
constructors that do not throw exceptions. Some of these are subclasses
of ArrayHandle. Add these move constructors to the
VTK_M_ARRAY_HANDLE_SUBCLASS macros so they get automatically added.
The original design of invoke and the transport infrastructure
relied on the implementation behavior of vtkm::cont types
such as ArrayHandle that used an internal shared_ptr to managed
state. This allowed passing by value instead of passing by
non-const ref when needing to transfer information to the device.
As VTK-m adds support for classes that use virtuals the ability
to pass by base pointer type allows for us to invoke worklets
using a base type without the risk of type slicing.
Additional by moving over to a non-const ref Invocation we
can update all transports that have 'output' to now be
by ref and therefore support types that can't be copied while
being 'more' correct.
