cobhan

README

Cobhan FFI

Cobhan FFI is a system for enabling shared code to be written in Rust or Go and consumed from all major languages/platforms in a safe and effective way, using easy helper functions to manage any unsafe data marshaling.

Types

• Supported types
  • int32 - 32bit signed integer
  • int64 - 64bit signed integer
  • float64 - double precision 64bit IEEE 754 floating point
  • Cobhan buffer - length delimited 8bit buffer (no null delimiters)
    • utf-8 encoded string
    • JSON
    • binary data
• Cobhan buffer details
  • Callers provide the output buffer allocation and capacity
  • Called functions can transparently return larger values via temporary files
  • Modern tmpfs is entirely memory backed
• Return values
  • Functions that return scalar values can return the value directly
    • Functions can use special case and return maximum positive or maximum negative or zero values to represent error or overflow conditions
    • Functions can allow scalar values to wrap
    • Functions should document their overflow / underflow behavior

Documentation

Index

• Constants
• func AllocateBuffer(length int) []byte
• func AllocateBytesBuffer(bytes []byte) ([]byte, int32)
• func AllocateStringBuffer(str string) ([]byte, int32)
• func AllowTempFileBuffers(flag bool)
• func BufferToBytes(srcPtr unsafe.Pointer) ([]byte, int32)
• func BufferToBytesSafe(src *[]byte) ([]byte, int32)
• func BufferToInt32(srcPtr unsafe.Pointer) (int32, int32)
• func BufferToInt32Safe(src *[]byte) (int32, int32)
• func BufferToInt64(srcPtr unsafe.Pointer) (int64, int32)
• func BufferToInt64Safe(src *[]byte) (int64, int32)
• func BufferToJson(srcPtr unsafe.Pointer) (map[string]interface{}, int32)
• func BufferToJsonSafe(src *[]byte) (map[string]interface{}, int32)
• func BufferToJsonStruct(srcPtr unsafe.Pointer, dst interface{}) int32
• func BufferToJsonStructSafe(src *[]byte, dst interface{}) int32
• func BufferToString(srcPtr unsafe.Pointer) (string, int32)
• func BufferToStringSafe(src *[]byte) (string, int32)
• func BytesToBuffer(bytes []byte, dstPtr unsafe.Pointer) int32
• func BytesToBufferSafe(bytes []byte, dst *[]byte) int32
• func CPtr(buf *[]byte) *C.char
• func CobhanErrorToString(cobhanError int32) string
• func Int32ToBuffer(value int32, dstPtr unsafe.Pointer) int32
• func Int32ToBufferSafe(value int32, dst *[]byte) int32
• func Int64ToBuffer(value int64, dstPtr unsafe.Pointer) int32
• func Int64ToBufferSafe(value int64, dst *[]byte) int32
• func JsonToBuffer(v interface{}, dstPtr unsafe.Pointer) int32
• func JsonToBufferSafe(v interface{}, dst *[]byte) int32
• func Ptr(buf *[]byte) unsafe.Pointer
• func SetDefaultBufferMaximum(max int)
• func StringToBuffer(str string, dstPtr unsafe.Pointer) int32
• func StringToBufferSafe(str string, dst *[]byte) int32

Constants

const BUFFER_HEADER_SIZE = (64 / 8) // 64 bit buffer header provides 8 byte alignment for data pointers

const DefaultBufferMaximum = math.MaxInt32

const ERR_BUFFER_TOO_LARGE = -2

ERR_BUFFER_TOO_LARGE One of the provided buffer lengths is too large

const ERR_BUFFER_TOO_SMALL = -3

ERR_BUFFER_TOO_SMALL One of the provided buffers was too small

const ERR_COPY_FAILED = -4

ERR_COPY_FAILED Failed to copy into the buffer (copy length != expected length)

const ERR_INVALID_UTF8 = -7

ERR_INVALID_UTF8 Buffer contains invalid utf-8

const ERR_JSON_DECODE_FAILED = -5

ERR_JSON_DECODE_FAILED Failed to decode a JSON buffer

const ERR_JSON_ENCODE_FAILED = -6

ERR_JSON_ENCODE_FAILED Failed to encode to JSON buffer

const ERR_NONE = 0

const ERR_NULL_PTR = -1

ERR_NULL_PTR One of the provided pointers is NULL / nil / 0

const ERR_READ_TEMP_FILE_FAILED = -8

const ERR_WRITE_TEMP_FILE_FAILED = -9

Functions

func AllocateBuffer

func AllocateBuffer(length int) []byte

func AllocateBytesBuffer

func AllocateBytesBuffer(bytes []byte) ([]byte, int32)

func AllocateStringBuffer

func AllocateStringBuffer(str string) ([]byte, int32)

func AllowTempFileBuffers

func AllowTempFileBuffers(flag bool)

func BufferToBytes

func BufferToBytes(srcPtr unsafe.Pointer) ([]byte, int32)

func BufferToBytesSafe

func BufferToBytesSafe(src *[]byte) ([]byte, int32)

func BufferToInt32

func BufferToInt32(srcPtr unsafe.Pointer) (int32, int32)

func BufferToInt32Safe

func BufferToInt32Safe(src *[]byte) (int32, int32)

func BufferToInt64

func BufferToInt64(srcPtr unsafe.Pointer) (int64, int32)

func BufferToInt64Safe

func BufferToInt64Safe(src *[]byte) (int64, int32)

func BufferToJson

func BufferToJson(srcPtr unsafe.Pointer) (map[string]interface{}, int32)

func BufferToJsonSafe

func BufferToJsonSafe(src *[]byte) (map[string]interface{}, int32)

func BufferToJsonStruct

func BufferToJsonStruct(srcPtr unsafe.Pointer, dst interface{}) int32

func BufferToJsonStructSafe

func BufferToJsonStructSafe(src *[]byte, dst interface{}) int32

func BufferToString

func BufferToString(srcPtr unsafe.Pointer) (string, int32)

func BufferToStringSafe

func BufferToStringSafe(src *[]byte) (string, int32)

func BytesToBuffer

func BytesToBuffer(bytes []byte, dstPtr unsafe.Pointer) int32

func BytesToBufferSafe

func BytesToBufferSafe(bytes []byte, dst *[]byte) int32

func CPtr

func CPtr(buf *[]byte) *C.char

func CobhanErrorToString

func CobhanErrorToString(cobhanError int32) string

func Int32ToBuffer

func Int32ToBuffer(value int32, dstPtr unsafe.Pointer) int32

func Int32ToBufferSafe

func Int32ToBufferSafe(value int32, dst *[]byte) int32

func Int64ToBuffer

func Int64ToBuffer(value int64, dstPtr unsafe.Pointer) int32

func Int64ToBufferSafe

func Int64ToBufferSafe(value int64, dst *[]byte) int32

func JsonToBuffer

func JsonToBuffer(v interface{}, dstPtr unsafe.Pointer) int32

func JsonToBufferSafe

func JsonToBufferSafe(v interface{}, dst *[]byte) int32

func Ptr

func Ptr(buf *[]byte) unsafe.Pointer

func SetDefaultBufferMaximum

func SetDefaultBufferMaximum(max int)

func StringToBuffer

func StringToBuffer(str string, dstPtr unsafe.Pointer) int32

func StringToBufferSafe

func StringToBufferSafe(str string, dst *[]byte) int32