commonMain.io.realm.kotlin.internal.interop.MemAllocator.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of cinterop-jvm Show documentation
Wrapper for interacting with Realm Kotlin native code. This artifact is not supposed to be consumed directly, but through 'io.realm.kotlin:gradle-plugin:3.0.0' instead.
The newest version!
/*
 * Copyright 2022 Realm Inc.
 *
 * Licensed 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.
 */

@file:JvmName("RealmValueAllocatorJvm")

package io.realm.kotlin.internal.interop

import org.mongodb.kbson.Decimal128
import kotlin.jvm.JvmName

/**
 * Allocator that handles allocation of C-API structs.
 */
interface MemAllocator {

    /**
     * Allocates a C-API `realm_value_t` struct.
     */
    fun allocRealmValueT(): RealmValueT

    /**
     * Allocates a contiguous list of `realm_value_t` structs.
     */
    fun allocRealmValueList(count: Int): RealmValueList

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` containing `null`.
     */
    // TODO optimize: investigate if we can statically create a null transport and reuse it
    fun nullTransport(): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_INT`.
     */
    fun longTransport(value: Long?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_BOOL`.
     */
    fun booleanTransport(value: Boolean?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_TIMESTAMP`.
     */
    fun timestampTransport(value: Timestamp?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_FLOAT`.
     */
    fun floatTransport(value: Float?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_DOUBLE`.
     */
    fun doubleTransport(value: Double?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_DECIMAL128`.
     */
    fun decimal128Transport(value: Decimal128?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_OBJECT_ID` from
     * an ObjectId's bytes.
     */
    fun objectIdTransport(value: ByteArray?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_UUID` from a
     * RealmUUID's bytes.
     */
    fun uuidTransport(value: ByteArray?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_DECIMAL128`.
     */
    fun decimal128Transport(value: ULongArray?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_LINK`.
     */
    fun realmObjectTransport(value: RealmObjectInterop?): RealmValue
}

/**
 * Allocator that handles allocation of C-API structs and (potential) deallocation. Deallocation
 * may occur due to the fact that the structs might be managed by the garbage collector e.g. on JVM
 * but the structs should be considered valid outside the scope of the allocator.
 */
interface MemTrackingAllocator : MemAllocator {

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_STRING`.
     */
    fun stringTransport(value: String?): RealmValue

    /**
     * Instantiates a [RealmValue] representing a `realm_value_t` of type `RLM_TYPE_BINARY`.
     */
    fun byteArrayTransport(value: ByteArray?): RealmValue

    /**
     * Instantiates a [RealmQueryArgumentList] representing a `realm_query_arg_t` that describe and
     * references the incoming [RealmValueList] arguments.
     */
    fun queryArgsOf(queryArgs: List): RealmQueryArgumentList

    /**
     * Frees resources linked to this allocator. See implementations for more details.
     */
    fun free() // TODO not possible to make it internal here but we could create extension functions for each platform?
}

/**
 * Creates an allocator that does **not** cleanup buffers upon completion.
 */
expect inline fun realmValueAllocator(): MemAllocator

/**
 * Creates an allocator that **does** cleanup buffers upon completion.
 */
expect inline fun trackingRealmValueAllocator(): MemTrackingAllocator

/**
 * Receives a [block] inside which C structs can be allocated for the purpose of retrieving values
 * from the C-API. See each platform-specific implementation for more details on how this is done.
 */
expect inline fun  getterScope(block: MemAllocator.() -> R): R

/**
 * Receives a [block] inside which C structs can be allocated for the purpose of sending values
 * to the C-API and whose potential data buffers are cleaned up after completion. See
 * [MemTrackingAllocator.free] for more details.
 */
// TODO optimize: distinguish between tracking and not tracking data buffers - we should avoid
//  leaking the allocators to the internal implementations.
inline fun  inputScope(block: MemTrackingAllocator.() -> R): R {
    val allocator = trackingRealmValueAllocator()
    val x = block(allocator)
    allocator.free()
    return x
}