/*

* Licensed to the Apache Software Foundation (ASF) under one or more

* contributor license agreements. See the NOTICE file distributed with

* this work for additional information regarding copyright ownership.

* The ASF licenses this file to You under the Apache License, Version 2.0

* (the "License"); you may not use this file except in compliance with

* the License. You may obtain a copy of the License at

*

* http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

package org.apache.arrow.c;

import static org.apache.arrow.c.NativeUtil.NULL;

import static org.apache.arrow.util.Preconditions.checkNotNull;

import java.nio.ByteBuffer;

import java.nio.ByteOrder;

import org.apache.arrow.c.jni.JniWrapper;

import org.apache.arrow.memory.ArrowBuf;

import org.apache.arrow.memory.BufferAllocator;

import org.apache.arrow.memory.ReferenceManager;

import org.apache.arrow.memory.util.MemoryUtil;

import org.apache.arrow.util.VisibleForTesting;

/**

* C Data Interface ArrowArray.

*

* <p>Represents a wrapper for the following C structure:

*

* <pre>

* struct ArrowArray {

* // Array data description

* int64_t length;

* int64_t null_count;

* int64_t offset;

* int64_t n_buffers;

* int64_t n_children;

* const void** buffers;

* struct ArrowArray** children;

* struct ArrowArray* dictionary;

*

* // Release callback

* void (*release)(struct ArrowArray*);

* // Opaque producer-specific data

* void* private_data;

* };

* </pre>

*/

public class ArrowArray implements BaseStruct {

private static final int SIZE_OF = 80;

private static final int INDEX_RELEASE_CALLBACK = 64;

private ArrowBuf data;

/** Snapshot of the ArrowArray raw data. */

public static class Snapshot {

public long length;

public long null_count;

public long offset;

public long n_buffers;

public long n_children;

public long buffers;

public long children;

public long dictionary;

public long release;

public long private_data;

/** Initialize empty ArrowArray snapshot. */

public Snapshot() {

length = NULL;

null_count = NULL;

offset = NULL;

n_buffers = NULL;

n_children = NULL;

buffers = NULL;

children = NULL;

dictionary = NULL;

release = NULL;

private_data = NULL;

}

}

/**

* Create ArrowArray from an existing memory address.

*

* <p>The resulting ArrowArray does not own the memory.

*

* @param memoryAddress Memory address to wrap

* @return A new ArrowArray instance

*/

public static ArrowArray wrap(long memoryAddress) {

return new ArrowArray(

new ArrowBuf(ReferenceManager.NO_OP, null, ArrowArray.SIZE_OF, memoryAddress));

}

/**

* Create ArrowArray by allocating memory.

*

* <p>The resulting ArrowArray owns the memory.

*

* @param allocator Allocator for memory allocations

* @return A new ArrowArray instance

*/

public static ArrowArray allocateNew(BufferAllocator allocator) {

ArrowArray array = new ArrowArray(allocator.buffer(ArrowArray.SIZE_OF));

array.markReleased();

return array;

}

ArrowArray(ArrowBuf data) {

checkNotNull(data, "ArrowArray initialized with a null buffer");

this.data = data;

}

/** Mark the array as released. */

public void markReleased() {

directBuffer().putLong(INDEX_RELEASE_CALLBACK, NULL);

}

@Override

public long memoryAddress() {

checkNotNull(data, "ArrowArray is already closed");

return data.memoryAddress();

}

@Override

public void release() {

long address = memoryAddress();

JniWrapper.get().releaseArray(address);

}

@Override

public void close() {

if (data != null) {

data.close();

data = null;

}

}

@VisibleForTesting

boolean isClosed() {

return data == null;

}

private ByteBuffer directBuffer() {

return MemoryUtil.directBuffer(memoryAddress(), ArrowArray.SIZE_OF)

.order(ByteOrder.nativeOrder());

}

/**

* Take a snapshot of the ArrowArray raw values.

*

* @return snapshot

*/

public Snapshot snapshot() {

ByteBuffer data = directBuffer();

Snapshot snapshot = new Snapshot();

snapshot.length = data.getLong();

snapshot.null_count = data.getLong();

snapshot.offset = data.getLong();

snapshot.n_buffers = data.getLong();

snapshot.n_children = data.getLong();

snapshot.buffers = data.getLong();

snapshot.children = data.getLong();

snapshot.dictionary = data.getLong();

snapshot.release = data.getLong();

snapshot.private_data = data.getLong();

return snapshot;

}

/** Write values from Snapshot to the underlying ArrowArray memory buffer. */

public void save(Snapshot snapshot) {

directBuffer()

.putLong(snapshot.length)

.putLong(snapshot.null_count)

.putLong(snapshot.offset)

.putLong(snapshot.n_buffers)

.putLong(snapshot.n_children)

.putLong(snapshot.buffers)

.putLong(snapshot.children)

.putLong(snapshot.dictionary)

.putLong(snapshot.release)

.putLong(snapshot.private_data);

}

}