Package 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
    Modifier and Type | Field | Description
    --- | --- | ---
    `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 | Description
    --- | ---
    `GPUObject​(GPUContext gCtx, GPUObject that, MatrixObject mat)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `acquireDeviceModifyDense()` |
    `boolean` | `acquireDeviceModifyDense​(boolean initialize)` |
    `boolean` | `acquireDeviceModifySparse()` |
    `boolean` | `acquireDeviceModifySparse​(boolean initialize)` |
    `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()

    - #### 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()

    - #### acquireDeviceModifyDense

          public boolean acquireDeviceModifyDense​(boolean initialize)

    - #### acquireDeviceModifySparse

          public boolean acquireDeviceModifySparse()

    - #### acquireDeviceModifySparse

          public boolean acquireDeviceModifySparse​(boolean initialize)

    - #### 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)