org.apache.sysds.runtime.instructions.gpu.context

## Class GPUObject

- java.lang.Object
- - org.apache.sysds.runtime.instructions.gpu.context.GPUObject

    public class GPUObject
    extends Object

Handle to a matrix block on the GPU

### Field Summary

Fields
`GPUObject` `lineageCachedChainHead` Next GPUObject that points to the same lineage cached GPU pointer
`GPUObject` `nextLineageCachedEntry` Head of the linked list of GPUObjects that point to the same lineage cached GPU pointer

### Constructor Summary

Constructors
Constructor and Description
`GPUObject(GPUContext gCtx, GPUObject that, MatrixObject mat)`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`boolean` `acquireDeviceModifyDense()`
`boolean` `acquireDeviceModifySparse()`
`boolean` `acquireDeviceRead(String opcode)`
`boolean` `acquireHostRead(String instName)` if the data is allocated on the GPU and is dirty, it is copied back to the host memory
`void` `addReadLock()`
`void` `addWriteLock()`
`void` `allocateAndFillDense(double v)` Allocates a dense matrix of size obtained from the attached matrix metadata and fills it up with a single value
`void` `allocateSparseAndEmpty()` Allocates a sparse and empty `GPUObject` This is the result of operations that are both non zero matrices.
`void` `clearData(String opcode, boolean eager)` Clears the data associated with this `GPUObject` instance
`void` `clearDensePointer()` Removes the dense pointer and potential soft reference
`void` `clearGPUObject()`
`Object` `clone()`
`static CSRPointer` `columnMajorDenseToRowMajorSparse(GPUContext gCtx, jcuda.jcusparse.cusparseHandle cusparseHandle, jcuda.Pointer densePtr, int rows, int cols)` Convenience method to convert a CSR matrix to a dense matrix on the GPU Since the allocated matrix is temporary, bookkeeping is not updated.
`void` `denseColumnMajorToRowMajor()` Convenience method.
`void` `denseRowMajorToColumnMajor()` Convenience method.
`void` `denseToSparse()` Converts this GPUObject from dense to sparse format.
`MatrixBlock` `evictFromDeviceToHostMB(String instName, boolean eagerDelete)`
`jcuda.Pointer` `getDensePointer()` Pointer to dense matrix
`long` `getDensePointerAddress()`
`CSRPointer` `getJcudaSparseMatrixPtr()` Pointer to sparse matrix
`MatrixObject` `getMatrixObject()`
`long` `getNnz(String instName, boolean recomputeDenseNNZ)` Being allocated is a prerequisite for computing nnz.
`static long` `getPointerAddress(jcuda.Pointer p)`
`long` `getSizeOnDevice()`
`CSRPointer` `getSparseMatrixCudaPointer()` Convenience method to directly examine the Sparse matrix on GPU
`boolean` `isAllocated()`
`boolean` `isDensePointerNull()` Checks if the dense pointer is null
`boolean` `isDirty()` Whether this block is dirty on the GPU
`boolean` `isLinCached()`
`boolean` `isLocked()`
`boolean` `isrmVarPending()`
`boolean` `isSparse()`
`boolean` `isSparseAndEmpty()` If this `GPUObject` is sparse and empty Being allocated is a prerequisite to being sparse and empty.
`void` `releaseInput()` Releases input allocated on GPU
`void` `releaseOutput()` releases output allocated on GPU
`void` `releaseReadLock()`
`void` `releaseWriteLock()`
`void` `resetReadWriteLock()`
`void` `setDensePointer(jcuda.Pointer densePtr)` Convenience method to directly set the dense matrix pointer on GPU
`void` `setDirty(boolean flag)`
`void` `setIsLinCached(boolean val)`
`void` `setrmVarPending(boolean val)`
`void` `setSparseMatrixCudaPointer(CSRPointer sparseMatrixPtr)` Convenience method to directly set the sparse matrix on GPU Needed for operations like cusparseDcsrgemm(cusparseHandle, int, int, int, int, int, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, Pointer, Pointer, Pointer)
`void` `sparseToColumnMajorDense()` More efficient method to convert sparse to dense but returns dense in column major format
`void` `sparseToDense()` Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format)
`void` `sparseToDense(String instructionName)` Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format) Also records per instruction invokation of sparseToDense.
`static int` `toIntExact(long l)`
`String` `toString()`
`static jcuda.Pointer` `transpose(GPUContext gCtx, jcuda.Pointer densePtr, int m, int n, int lda, int ldc)` Transposes a dense matrix on the GPU by calling the cublasDgeam operation

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### lineageCachedChainHead

    public GPUObject lineageCachedChainHead

Next GPUObject that points to the same lineage cached GPU pointer

#### nextLineageCachedEntry

    public GPUObject nextLineageCachedEntry

Head of the linked list of GPUObjects that point to the same lineage cached GPU pointer

### Constructor Detail

#### GPUObject

    public GPUObject(GPUContext gCtx,
                     GPUObject that,
                     MatrixObject mat)

### Method Detail

#### getDensePointer

    public jcuda.Pointer getDensePointer()

Pointer to dense matrix

Returns:
  a pointer to the dense matrix

#### isDensePointerNull

    public boolean isDensePointerNull()

Checks if the dense pointer is null

Returns:
  if the state of dense pointer is null

#### clearDensePointer

    public void clearDensePointer()

Removes the dense pointer and potential soft reference

#### getMatrixObject

    public MatrixObject getMatrixObject()

#### setDensePointer

    public void setDensePointer(jcuda.Pointer densePtr)

Convenience method to directly set the dense matrix pointer on GPU

Parameters:
  `densePtr` - dense pointer

#### setDirty

    public void setDirty(boolean flag)

#### clone

    public Object clone()

Overrides:
  `clone` in class `Object`

#### transpose

    public static jcuda.Pointer transpose(GPUContext gCtx,
                                          jcuda.Pointer densePtr,
                                          int m,
                                          int n,
                                          int lda,
                                          int ldc)

Transposes a dense matrix on the GPU by calling the cublasDgeam operation

Parameters:
  `gCtx` - a valid `GPUContext`
  `densePtr` - Pointer to dense matrix on the GPU
  `m` - rows in ouput matrix
  `n` - columns in output matrix
  `lda` - rows in input matrix
  `ldc` - columns in output matrix
Returns:
  transposed matrix

#### columnMajorDenseToRowMajorSparse

    public static CSRPointer columnMajorDenseToRowMajorSparse(GPUContext gCtx,
                                                              jcuda.jcusparse.cusparseHandle cusparseHandle,
                                                              jcuda.Pointer densePtr,
                                                              int rows,
                                                              int cols)

Convenience method to convert a CSR matrix to a dense matrix on the GPU Since the allocated matrix is temporary, bookkeeping is not updated. Also note that the input dense matrix is expected to be in COLUMN MAJOR FORMAT Caller is responsible for deallocating memory on GPU.

Parameters:
  `gCtx` - a valid `GPUContext`
  `cusparseHandle` - handle to cusparse library
  `densePtr` - [in] dense matrix pointer on the GPU in row major
  `rows` - number of rows
  `cols` - number of columns
Returns:
  CSR (compressed sparse row) pointer

#### getSparseMatrixCudaPointer

    public CSRPointer getSparseMatrixCudaPointer()

Convenience method to directly examine the Sparse matrix on GPU

Returns:
  CSR (compressed sparse row) pointer

#### setSparseMatrixCudaPointer

    public void setSparseMatrixCudaPointer(CSRPointer sparseMatrixPtr)

Convenience method to directly set the sparse matrix on GPU Needed for operations like cusparseDcsrgemm(cusparseHandle, int, int, int, int, int, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, Pointer, Pointer, Pointer)

Parameters:
  `sparseMatrixPtr` - CSR (compressed sparse row) pointer

#### denseToSparse

    public void denseToSparse()

Converts this GPUObject from dense to sparse format.

#### denseRowMajorToColumnMajor

    public void denseRowMajorToColumnMajor()

Convenience method. Converts Row Major Dense Matrix to Column Major Dense Matrix

#### denseColumnMajorToRowMajor

    public void denseColumnMajorToRowMajor()

Convenience method. Converts Column Major Dense Matrix to Row Major Dense Matrix

#### sparseToDense

    public void sparseToDense()

Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format)

#### sparseToDense

    public void sparseToDense(String instructionName)

Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format) Also records per instruction invokation of sparseToDense.

Parameters:
  `instructionName` - Name of the instruction for which statistics are recorded in `GPUStatistics`

#### sparseToColumnMajorDense

    public void sparseToColumnMajorDense()

More efficient method to convert sparse to dense but returns dense in column major format

#### isSparse

    public boolean isSparse()

#### isAllocated

    public boolean isAllocated()

#### allocateSparseAndEmpty

    public void allocateSparseAndEmpty()

Allocates a sparse and empty `GPUObject` This is the result of operations that are both non zero matrices.

#### allocateAndFillDense

    public void allocateAndFillDense(double v)

Allocates a dense matrix of size obtained from the attached matrix metadata and fills it up with a single value

Parameters:
  `v` - value to fill up the dense matrix

#### isSparseAndEmpty

    public boolean isSparseAndEmpty()

If this `GPUObject` is sparse and empty Being allocated is a prerequisite to being sparse and empty.

Returns:
  true if sparse and empty

#### getNnz

    public long getNnz(String instName,
                       boolean recomputeDenseNNZ)

Being allocated is a prerequisite for computing nnz. Note: if the matrix is in dense format, it explicitly re-computes the number of nonzeros.

Parameters:
  `instName` - instruction name
  `recomputeDenseNNZ` - recompute NNZ if dense
Returns:
  the number of nonzeroes

#### acquireDeviceRead

    public boolean acquireDeviceRead(String opcode)

#### acquireDeviceModifyDense

    public boolean acquireDeviceModifyDense()

#### acquireDeviceModifySparse

    public boolean acquireDeviceModifySparse()

#### acquireHostRead

    public boolean acquireHostRead(String instName)

if the data is allocated on the GPU and is dirty, it is copied back to the host memory

Parameters:
  `instName` - name of the instruction
Returns:
  true if a copy to host happened, false otherwise

#### isLocked

    public boolean isLocked()

#### addReadLock

    public void addReadLock()

#### addWriteLock

    public void addWriteLock()

#### releaseReadLock

    public void releaseReadLock()

#### releaseWriteLock

    public void releaseWriteLock()

#### resetReadWriteLock

    public void resetReadWriteLock()

#### releaseInput

    public void releaseInput()

Releases input allocated on GPU

#### releaseOutput

    public void releaseOutput()

releases output allocated on GPU

#### getSizeOnDevice

    public long getSizeOnDevice()

#### toIntExact

    public static int toIntExact(long l)

#### evictFromDeviceToHostMB

    public MatrixBlock evictFromDeviceToHostMB(String instName,
                                               boolean eagerDelete)
                                        throws DMLRuntimeException

Throws:
  `DMLRuntimeException`

#### clearData

    public void clearData(String opcode,
                          boolean eager)
                   throws DMLRuntimeException

Clears the data associated with this `GPUObject` instance

Parameters:
  `opcode` - opcode of the instruction
  `eager` - whether to be done synchronously or asynchronously
Throws:
  `DMLRuntimeException` - if error occurs

#### clearGPUObject

    public void clearGPUObject()

#### getJcudaSparseMatrixPtr

    public CSRPointer getJcudaSparseMatrixPtr()

Pointer to sparse matrix

Returns:
  ?

#### isDirty

    public boolean isDirty()

Whether this block is dirty on the GPU

Returns:
  ?

#### setIsLinCached

    public void setIsLinCached(boolean val)

#### isLinCached

    public boolean isLinCached()

#### setrmVarPending

    public void setrmVarPending(boolean val)

#### isrmVarPending

    public boolean isrmVarPending()

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

#### getDensePointerAddress

    public long getDensePointerAddress()

#### getPointerAddress

    public static long getPointerAddress(jcuda.Pointer p)