Skip to content

Commit be61879

Browse files
authored
[objective_c] API docs (#3708)
1 parent a18dd11 commit be61879

13 files changed

Lines changed: 109 additions & 9 deletions

‎pkgs/objective_c/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ https://pub.dev/packages/ffigen
1515
For general information about interop with Objective C, see
1616
https://dart.dev/guides/libraries/objective-c-interop
1717

18+
You can find more documentation about Objective-C interop using FFIgen in
19+
the TOPICS section in [FFIgen's API documentation](https://pub.dev/documentation/ffigen/latest/).
20+
1821
## Memory management
1922

2023
Objective C and Dart use different styles of memory management. Dart is garbage
@@ -36,3 +39,6 @@ reference counting issue, it may occasionally be necessary to manually control
3639
the ref count. The ref count of the Objective C object can be controlled from
3740
Dart by the `retain` and `release` options in the Dart wrapper object
3841
constructors, and by the `retainAndReturnPointer()` and `release()` methods.
42+
43+
For more details on avoiding reference cycles and leaks, see the
44+
[Objective-C Memory Management topic](https://pub.dev/documentation/ffigen/latest/topics/Objective-C%20Memory%20Management-topic.html).

‎pkgs/objective_c/lib/src/autorelease.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ import 'runtime_bindings_generated.dart';
3636
/// here (the [Future] it returns will not be awaited). Objective-C autorelease
3737
/// pools form a strict stack, and allowing async execution gaps inside the pool
3838
/// scope could easily break this nesting, so async functions are not supported.
39+
///
40+
/// See the [Objective-C Memory Management guide](https://pub.dev/documentation/ffigen/latest/topics/Objective-C%20Memory%20Management-topic.html).
3941
T autoReleasePool<T>(T Function() function) {
4042
final pool = autoreleasePoolPush();
4143
try {

‎pkgs/objective_c/lib/src/globals.dart‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,30 +7,39 @@
77
import 'objective_c_bindings_generated.dart';
88
import 'runtime_bindings_generated.dart' as r;
99

10+
/// Key in a key-value observing change dictionary for the index set of changed
11+
/// objects.
1012
NSString get NSKeyValueChangeIndexesKey => NSString.fromPointer(
1113
r.NSKeyValueChangeIndexesKey,
1214
retain: true,
1315
release: true,
1416
);
1517

18+
/// Key in a key-value observing change dictionary for the kind of change.
1619
NSString get NSKeyValueChangeKindKey => NSString.fromPointer(
1720
r.NSKeyValueChangeKindKey,
1821
retain: true,
1922
release: true,
2023
);
2124

25+
/// Key in a key-value observing change dictionary for the new property value.
2226
NSString get NSKeyValueChangeNewKey =>
2327
NSString.fromPointer(r.NSKeyValueChangeNewKey, retain: true, release: true);
2428

29+
/// Key in a key-value observing change dictionary indicating whether the
30+
/// notification is sent prior to the change.
2531
NSString get NSKeyValueChangeNotificationIsPriorKey => NSString.fromPointer(
2632
r.NSKeyValueChangeNotificationIsPriorKey,
2733
retain: true,
2834
release: true,
2935
);
3036

37+
/// Key in a key-value observing change dictionary for the old property value.
3138
NSString get NSKeyValueChangeOldKey =>
3239
NSString.fromPointer(r.NSKeyValueChangeOldKey, retain: true, release: true);
3340

41+
/// Key in an [NSError] `userInfo` dictionary for the localized description
42+
/// string.
3443
NSString get NSLocalizedDescriptionKey => NSString.fromPointer(
3544
r.NSLocalizedDescriptionKey,
3645
retain: true,

‎pkgs/objective_c/lib/src/internal.dart‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,8 +287,20 @@ abstract final class _ObjCReference<T extends NativeType>
287287
_isReleased.value = true;
288288
}
289289

290+
/// Manually releases the underlying reference.
291+
///
292+
/// Throws a [DoubleReleaseError] if this reference has already been
293+
/// released.
294+
///
295+
/// See the [Objective-C Memory Management guide](https://pub.dev/documentation/ffigen/latest/topics/Objective-C%20Memory%20Management-topic.html).
290296
void release() => _release(r.objectRelease);
291297

298+
/// Releases the reference by adding it to the current autorelease pool.
299+
///
300+
/// Throws a [DoubleReleaseError] if this reference has already been
301+
/// released.
302+
///
303+
/// See the [Objective-C Memory Management guide](https://pub.dev/documentation/ffigen/latest/topics/Objective-C%20Memory%20Management-topic.html).
292304
Pointer<T> autorelease() {
293305
_release(r.objectAutorelease);
294306
return _finalizable.ptr;
@@ -301,6 +313,10 @@ abstract final class _ObjCReference<T extends NativeType>
301313
@override
302314
int get hashCode => _finalizable.ptr.hashCode;
303315

316+
/// The raw pointer to the underlying Objective-C object or block.
317+
///
318+
/// Throws a [UseAfterReleaseError] if this reference has already been
319+
/// released.
304320
Pointer<T> get pointer {
305321
if (isReleased) {
306322
throw UseAfterReleaseError();
@@ -309,12 +325,22 @@ abstract final class _ObjCReference<T extends NativeType>
309325
return _finalizable.ptr;
310326
}
311327

328+
/// Retains the underlying reference and returns the raw pointer.
329+
///
330+
/// The caller takes ownership of the retained reference (+1 retain count)
331+
/// and is responsible for manually releasing it.
332+
///
333+
/// See the [Objective-C Memory Management guide](https://pub.dev/documentation/ffigen/latest/topics/Objective-C%20Memory%20Management-topic.html).
312334
Pointer<T> retainAndReturnPointer() {
313335
final ptr = pointer;
314336
_retain(ptr);
315337
return ptr;
316338
}
317339

340+
/// Retains the underlying reference and adds it to the current autorelease
341+
/// pool, returning the raw pointer.
342+
///
343+
/// See the [Objective-C Memory Management guide](https://pub.dev/documentation/ffigen/latest/topics/Objective-C%20Memory%20Management-topic.html).
318344
Pointer<T> retainAndAutorelease() {
319345
final ptr = pointer;
320346
_retain(ptr);
@@ -341,6 +367,10 @@ class _ObjCRefHolder<T extends NativeType, Ref extends _ObjCReference<T>> {
341367
int get hashCode => ref.hashCode;
342368
}
343369

370+
/// A reference to an Objective-C object.
371+
///
372+
/// This is an internal API for use by ffigen bindings and internal machinery.
373+
/// Do not use directly.
344374
@pragma('vm:deeply-immutable')
345375
final class ObjCObjectRef extends _ObjCReference<r.ObjCObjectImpl> {
346376
ObjCObjectRef(ObjectPtr ptr, {required super.retain, required super.release})
@@ -354,6 +384,9 @@ final class ObjCObjectRef extends _ObjCReference<r.ObjCObjectImpl> {
354384
}
355385

356386
/// Base class for all Objective-C objects.
387+
///
388+
/// For details on Objective-C runtime types and subtyping with Dart extension
389+
/// types, see the [Objective-C Runtime Types guide](https://pub.dev/documentation/ffigen/latest/topics/Objective-C%20Runtime%20Types-topic.html).
357390
class ObjCObject extends _ObjCRefHolder<r.ObjCObjectImpl, ObjCObjectRef> {
358391
ObjCObject(ObjectPtr ptr, {required bool retain, required bool release})
359392
: super(ObjCObjectRef(ptr, retain: retain, release: release));
@@ -395,6 +428,10 @@ bool _isValidClass(ObjectPtr clazz, {bool forceReloadClasses = false}) {
395428
// a protocol and an interface.
396429
typedef ObjCProtocol = ObjCObject;
397430

431+
/// A reference to an Objective-C block.
432+
///
433+
/// This is an internal API for use by ffigen bindings and internal machinery.
434+
/// Do not use directly.
398435
@pragma('vm:deeply-immutable')
399436
final class ObjCBlockRef extends _ObjCReference<c.ObjCBlockImpl> {
400437
ObjCBlockRef(BlockPtr ptr, {required super.retain, required super.release})

‎pkgs/objective_c/lib/src/ns_data.dart‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ extension NSDataExtensions on NSData {
1919
}
2020

2121
/// Return a list containing the contents of the [NSData].
22+
///
23+
/// Copies the bytes from native memory into the Dart heap.
2224
Uint8List toList() {
2325
if (bytes.address == 0 || length == 0) {
2426
return Uint8List(0);
@@ -32,6 +34,8 @@ extension NSDataListExtension on List<int> {
3234
/// Return a [NSData] containing the contents of the [List] interpreted as
3335
/// bytes.
3436
///
37+
/// Copies the bytes from the Dart heap into native memory.
38+
///
3539
/// The elements of the [List] should be integers in the range 0 to 255. Any
3640
/// integer, which is not in that range, is converted to a byte as if by
3741
/// `value.toUnsigned(8)`.

‎pkgs/objective_c/lib/src/ns_input_stream.dart‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
2+
// for details. All rights reserved. Use of this source code is governed by a
3+
// BSD-style license that can be found in the LICENSE file.
4+
15
import 'dart:async';
26
import 'dart:ffi';
37
import 'dart:isolate';
@@ -21,12 +25,6 @@ extension NSInputStreamStreamExtension on Stream<List<int>> {
2125
/// > [Stream].
2226
///
2327
/// > [!IMPORTANT]
24-
/// > `NSInputStream.read` must be called from a different thread or [Isolate]
25-
/// > than the one that calls `toNSInputStream`. Otherwise,
26-
/// > `NSInputStream.read` will deadlock waiting for data to be added from the
27-
/// > [Stream].
28-
///
29-
/// > [!IMPORTANT]
3028
/// > `toNSInputStream` creates a reference cycle between Dart and
3129
/// > Objective-C. Unless this cycle is broken, the [Isolate] calling
3230
/// > `toNSInputStream` will never exit. The cycle can be broken by calling

‎pkgs/objective_c/lib/src/ns_mutable_data.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ extension NSMutableDataListExtension on List<int> {
4646
/// Return a [NSMutableData] containing the contents of the [List] interpreted
4747
/// as bytes.
4848
///
49+
/// Copies the bytes from the Dart heap into native memory.
50+
///
4951
/// The elements of the [List] should be integers in the range 0 to 255. Any
5052
/// integer, which is not in that range, is converted to a byte as if by
5153
/// `value.toUnsigned(8)`.

‎pkgs/objective_c/lib/src/observer.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,5 +44,7 @@ class Observation {
4444
/// Stops the [Observer] object from receiving change notifications.
4545
void remove() => _observation.remove();
4646

47+
/// The raw pointer to the underlying Objective-C observer object, for
48+
/// debugging and testing.
4749
Pointer<Void> get debugObserver => _observation.debugObserver();
4850
}

‎pkgs/objective_c/lib/src/os_version.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Version _osVersion = () {
2020
///
2121
/// Designed to replace Objective-C's `@available` check.
2222
///
23-
/// The each platform's version is optional, and the function returns false if
23+
/// Each platform's version is optional, and the function returns false if
2424
/// no version is provided for the current platform.
2525
bool checkOSVersion({Version? iOS, Version? macOS}) {
2626
if (Platform.isIOS) return _checkOSVersionImpl(iOS);

‎pkgs/objective_c/lib/src/protocol_builder.dart‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,23 @@ import 'objective_c_bindings_generated.dart' as objc;
1515
import 'runtime_bindings_generated.dart' as r;
1616
import 'selector.dart';
1717

18-
/// Helper class for building Objective C objects that implement protocols.
18+
/// Helper class for building Objective-C objects that implement protocols.
19+
///
20+
/// Use the `$Builder` class generated by `ffigen` for the protocol to
21+
/// mplement protocol methods. For example:
22+
///
23+
/// <!-- file://./../../tool/snippets/protocol_builder_snippet.dart#protocol_builder -->
24+
/// ```dart
25+
/// // Build an object that implements an Objective-C protocol.
26+
/// final builder = ObjCProtocolBuilder();
27+
/// NSStreamDelegate$Builder.addToBuilder(
28+
/// builder,
29+
/// stream_handleEvent_: (stream, event) {
30+
/// // Handle stream event.
31+
/// },
32+
/// );
33+
/// final delegate = NSStreamDelegate.as(builder.build());
34+
/// ```
1935
class ObjCProtocolBuilder {
2036
final objc.DartProtocolBuilder _builder;
2137
var _built = false;

0 commit comments

Comments
 (0)