GPUObject (SystemML 1.2.0 API)

java.lang.Object
- org.apache.sysml.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 and Description
`protected boolean`	`dirty` whether the block attached to this `GPUContext` is dirty on the device and needs to be copied back to host
`protected boolean`	`isSparse` Whether this block is in sparse format
`protected LongAdder`	`readLocks` number of read locks on this object (this GPUObject is being used in a current instruction)
`protected boolean`	`writeLock` whether write lock on this object (this GPUObject is being used in a current instruction)

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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
`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.
`protected void`	`copyFromDeviceToHost(String instName, boolean isEviction, boolean eagerDelete)` Copies the data from device to host.
`void`	`denseColumnMajorToRowMajor()` Convenience method.
`void`	`denseRowMajorToColumnMajor()` Convenience method.
`void`	`denseToSparse()` Converts this GPUObject from dense to sparse format.
`jcuda.Pointer`	`getDensePointer()` Pointer to dense matrix
`CSRPointer`	`getJcudaSparseMatrixPtr()` Pointer to sparse matrix
`long`	`getNnz(String instName, boolean recomputeDenseNNZ)` Being allocated is a prerequisite for computing nnz.
`protected 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`	`isLocked()`
`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`	`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, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - dirty
```
protected boolean dirty
```
    whether the block attached to this GPUContext is dirty on the device and needs to be copied back to host
  - readLocks
```
protected LongAdder readLocks
```
    number of read locks on this object (this GPUObject is being used in a current instruction)
  - writeLock
```
protected boolean writeLock
```
    whether write lock on this object (this GPUObject is being used in a current instruction)
  - isSparse
```
protected boolean isSparse
```
    Whether this block is in sparse format
- 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
  - setDensePointer
```
public void setDensePointer(jcuda.Pointer densePtr)
```
    Convenience method to directly set the dense matrix pointer on GPU
    
    Parameters:
    
    densePtr - dense pointer
  - 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
```
protected long getSizeOnDevice()
```
  - toIntExact
```
public static int toIntExact(long l)
```
  - copyFromDeviceToHost
```
protected void copyFromDeviceToHost(String instName,
                                    boolean isEviction,
                                    boolean eagerDelete)
                             throws DMLRuntimeException
```
    Copies the data from device to host. Currently eagerDelete and isEviction are both provided for better control in different scenarios. In future, we can force eagerDelete if isEviction is true, else false.
    
    Parameters:
    
    instName - opcode of the instruction for fine-grained statistics
    
    isEviction - is called for eviction
    
    eagerDelete - whether to perform eager deletion of the device data.
    
    Throws:
    
    DMLRuntimeException - if error occurs
  - 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
  - getJcudaSparseMatrixPtr
```
public CSRPointer getJcudaSparseMatrixPtr()
```
    Pointer to sparse matrix
    
    Returns:
    
    ?
  - isDirty
```
public boolean isDirty()
```
    Whether this block is dirty on the GPU
    
    Returns:
    
    ?
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class GPUObject

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

dirty

readLocks

writeLock

isSparse

Method Detail

getDensePointer

isDensePointerNull

clearDensePointer

setDensePointer

clone

transpose

columnMajorDenseToRowMajorSparse

getSparseMatrixCudaPointer

setSparseMatrixCudaPointer

denseToSparse

denseRowMajorToColumnMajor

denseColumnMajorToRowMajor

sparseToDense

sparseToDense

sparseToColumnMajorDense

isSparse

isAllocated

allocateSparseAndEmpty

allocateAndFillDense

isSparseAndEmpty

getNnz

acquireDeviceRead

acquireDeviceModifyDense

acquireDeviceModifySparse

acquireHostRead

isLocked

addReadLock

addWriteLock

releaseReadLock

releaseWriteLock

resetReadWriteLock

releaseInput

releaseOutput

getSizeOnDevice

toIntExact

copyFromDeviceToHost

clearData

getJcudaSparseMatrixPtr

isDirty

toString