| // Copyright (c) 2019, the Dart project authors. Please see the AUTHORS file |
| // for details. All rights reserved. Use of this source code is governed by a |
| // BSD-style license that can be found in the LICENSE file |
| |
| /// {@category VM} |
| /// {@nodoc} |
| library dart.ffi; |
| |
| part "native_type.dart"; |
| part "annotations.dart"; |
| part "dynamic_library.dart"; |
| |
| /// Allocate [count] elements of type [T] on the C heap with malloc() and return |
| /// a pointer to the newly allocated memory. |
| /// |
| /// Note that the memory are uninitialized. |
| /// |
| /// TODO(dacoharkes): change signature to T allocate<T extends Pointer>() ? |
| /// This would enable us to allocate structs. However how do we know the size of |
| /// structs? https://github.com/dart-lang/sdk/issues/35782 |
| external Pointer<T> allocate<T extends NativeType>({int count: 1}); |
| |
| /// Construction from raw value |
| external T fromAddress<T extends Pointer>(int ptr); |
| |
| /// number of bytes used by native type T |
| external int sizeOf<T extends NativeType>(); |
| |
| /// Convert Dart function to a C function pointer, automatically marshalling |
| /// the arguments and return value |
| /// |
| /// Note: this is not implemented, always returns Pointer with address 0. |
| /// |
| /// TODO(dacoharkes): Implement this feature. |
| /// https://github.com/dart-lang/sdk/issues/35761 |
| external Pointer<NativeFunction<T>> fromFunction<T extends Function>( |
| @DartRepresentationOf("T") Function f); |
| |
| /* |
| /// TODO(dacoharkes): Implement this feature. |
| /// https://github.com/dart-lang/sdk/issues/35770 |
| /// Return a pointer object that has a finalizer attached to it. When this |
| /// pointer object is collected by GC the given finalizer is invoked. |
| /// |
| /// Note: the pointer object passed to the finalizer is not the same as |
| /// the pointer object that is returned from [finalizable] - it points |
| /// to the same memory region but has different identity. |
| external Pointer<T> finalizable<T extends NativeType>( |
| Pointer<T> p, void finalizer(Pointer<T> ptr)); |
| */ |
| |
| /// Represents a pointer into the native C memory. |
| class Pointer<T extends NativeType> extends NativeType { |
| const Pointer(); |
| |
| /// Store a Dart value into this location. |
| /// |
| /// The [value] is automatically marshalled into its C representation. |
| /// Note that ints which do not fit in [T] are truncated and sign extended, |
| /// and doubles stored into Pointer<[Float]> lose precision. |
| external void store(@DartRepresentationOf("T") Object value); |
| |
| /// Load a Dart value from this location. |
| /// |
| /// The value is automatically unmarshalled from its C representation. |
| external R load<@DartRepresentationOf("T") R>(); |
| |
| /// Access to the raw pointer value. |
| external int get address; |
| |
| /// Pointer arithmetic (takes element size into account). |
| external Pointer<T> elementAt(int index); |
| |
| /// Pointer arithmetic (byte offset). |
| /// |
| /// TODO(dacoharkes): remove this? |
| /// https://github.com/dart-lang/sdk/issues/35883 |
| external Pointer<T> offsetBy(int offsetInBytes); |
| |
| /// Cast Pointer<T> to a (subtype of) Pointer<V>. |
| external U cast<U extends Pointer>(); |
| |
| /// Convert to Dart function, automatically marshalling the arguments |
| /// and return value. |
| /// |
| /// Can only be called on [Pointer]<[NativeFunction]>. |
| external R asFunction<@DartRepresentationOf("T") R extends Function>(); |
| |
| /// Free memory on the C heap pointed to by this pointer with free(). |
| /// |
| /// Note that this zeros out the address. |
| external void free(); |
| |
| /// Equality for Pointers only depends on their address. |
| bool operator ==(other) { |
| if (other == null) return false; |
| return address == other.address; |
| } |
| |
| /// The hash code for a Pointer only depends on its address. |
| int get hashCode { |
| return address.hashCode; |
| } |
| } |