Learning how to create a simple version of Retrofit from scratch

Mocks or Fakes? Which one do you choose? I’m kidding, I am not going to enter such a long tedious, and philosophical programming topic. The focus of this article will be on how a mock library works. After all, it looks pretty magical that libraries like Mockito and Mockk can alter the behavior of existing classes.

This article is part of a series. To see the other articles click here.

In the last article, I introduced you to the Proxy class and I showed you how Retrofit uses it to dynamically implement a REST API interface. We saw that we could use it to intercept calls to the methods of an interface. Unfortunately Proxy does not work with classes, which is essential to a proper mock library. In this article, we are going to see how we can overcome that limitation with bytecode generation libraries.

Byte Code Generation Libraries

As mentioned by Fabian Lange, “An often overlooked feature of the Java platform is the ability to modify a program’s bytecode before it is executed by the JVM’s interpreter or just-in-time (JIT) compiler”. Such a feature is explored by bytecode generation libraries which allow the development of code capable of creating new classes or modifying existing ones at runtime. That, in turn, enables a wide range of applications such as mocks, profiling, security, and aspect-oriented programming, among others.

One of the most popular code generation libraries were cglib, which stands for code generation library. Let’s see how we could implement an approach similar to the Proxy class using cglib:

On line 10, I created the inline reified function createMock, so I can access the Class object. The Enhancer class generates dynamic subclasses to enable method interception. In line 11, I set the superclass to be the type to be mocked — in fact, we are creating a subclass. In line 12, I set the callback to interceptor, which will work similarly to the InvocationHandler that we used with Proxy in the previous article. Whenever a method on the mocked object is called, interceptor will called with that method and its arguments. Line 13 creates an instance of the dynamically defined subclass and casts it to the mocked typed. Finally, lines 16 through 23 implement the MethodInterceptor, which uses reflection to check the method name and return the mocked response.

ByteBuddy

I hope the cglib example gave you a basic idea of how we will implement our simple version of Mockito/Mockk. If you paid attention, I said cglib was one of the most popular code generation libraries. It was because it is no longer being maintained and may not work with newer JDKs. The recommendation now is to use ByteBuddy. In fact, that is the library that powers Mockito and Mockk, the mocking frameworks you certainly used if you wrote unit tests for Java, Kotlin, or Android. With ByteBuddy we can create subclasses, override methods, define new classes, delegate, or even redefine existing classes.

As an example of what ByteBudy can do, we will re-implement the following class Person at runtime:

class Person(a: String, b: String) {
    private val firstName: String = a
    private val lastName: String = b
    override fun toString(): String {
        return "$firstName $lastName is the person's name"
    }
}

First, we add the dependencies to our build.gradle.kts file (versions were the latest at the time of writing this article).

dependencies {
  ...
    implementation("net.bytebuddy:byte-buddy:1.14.14")
    implementation("net.bytebuddy:byte-buddy-agent:1.14.14")
    implementation("org.jetbrains.kotlin:kotlin-reflect:1.9.23")
  ...
}

And here is the code:

Most of the code should be straightforward:

• Lines 13 and 14 define the new class. It is named Person and it is a subclass of Any like any other Kotlin class.
• Lines 15 and 16 define the fields firstName and lastName.
• Lines 17–23 define the constructor. The most important line here is the one that calls intercept . That is the function that specifies the implementation of the method. In this case, we first call the constructor of Any, the superclass, and then we set the firstName and lastName fields with the parameters that were passed to the constructor being defined.
• Lines 24 and 25 override Any::toString() by delegating it to the PersonToString object. The FieldValue annotations tells ByteBudy to bind the parameters of the function with fields of the class being defined.
• Lines 26 to 28 finish the creation of the class and load it into the classpath, so it is available to be used.
• Lines 39 to 46 show how to use the newly defined class. We need to use reflection to create an instance and call the methods. The output of those lines is the following:

Person
[private java.lang.String Person.firstName, private java.lang.String Person.lastName]
John Smith is the person's name

Creating the mock library

Now that we have a basic idea of how to use ByteBuddy, let’s try to create our own mock library. We will implement a very simple version of Mockk and Mockito that could be used like this:

val mocked: ClassToBeMocked = mock {
    whenever(ClassToBeMocked::method) returns returnValue
}

Implementing the DSL

The first step is to define the DSL to collect the mock configurations.

interface MockScopeDsl {
    fun <T> whenever(method: KFunction<T>): KFunction<T>
    infix fun <T> KFunction<T>.returns(returnValue: T)
}

class MockScopeDslImpl : MockScopeDsl {
    val mockedMethods = mutableMapOf<KFunction<*>, Any?>()
    override fun <T> whenever(method: KFunction<T>) = method
    override fun <T> KFunction<T>.returns(returnValue: T) {
        mockedMethods[this@returns] = returnValue
    }
}

The mock scope of our DSL has two functions. The functionwhenever does not do much. It just returns its argument. However, it makes the whole expression more legible and it forces the expression to start with a KFunction, the Kotlin equivalent to Java’s Method. The infix extension returns stores the function and the return value in a map.

Implementing the mock function

Now that we have a nice DSL, let’s implement the function that creates the mock.

inline fun <reified T : Any> mock(configBlock: MockScopeDsl.() -> Unit): T {
    val mockScope = MockScopeDslImpl()
    mockScope.configBlock()
    var subClassProto: DynamicType.Builder<T> = ByteBuddy().subclass(T::class.java)
    mockScope.mockedMethods.forEach { (kFunction, returnValue) ->
        subClassProto = subClassProto
            .method(ElementMatchers.`is`(kFunction.javaMethod!!))
            .intercept(FixedValue.value(returnValue!!))
    }
    val clazz = subClassProto.make().load(T::class.java.classLoader).loaded as Class<T>

    return clazz.getDeclaredConstructor().newInstance()
}

The mock function is inlined reified so we can have access to the Class object of the class we want to mock. The function receives the DSL configBlock and calls it on an instance of MockScopeDslImpl to collect the mocked methods on a map. We then dynamically create a subclass of the class to be mocked using ByteBuddy. Next, we iterate over the map of mocked methods telling ByteBuddy to intercept the respective method and return the value defined by the DSL. And finally, we finish the building of the mock class and load it into the classpath.

The full implementation

Here is the complete code for our mock library including a sample JUnit test to demonstrate its usage

In this instance of the series, I told you how Mockito works. If you are curious about how Retrofit and Butterknife work do not forget to check the other articles of the series:

Let Kotlin do the code for you

References

• BAELDUNG — A Guide to Byte Buddy https://www.baeldung.com/byte-buddy
• WINTERHALTER, Rafael — Using Byte Buddy for proxy creation https://mydailyjava.blogspot.com/2022/02/using-byte-buddy-for-proxy-creation.html
• ByteBuddy — Why runtime code generation?https://bytebuddy.net/#/tutorial
• LANGE, Fabian — Runtime Code Generation with Byte Buddy https://blogs.oracle.com/javamagazine/post/runtime-code-generation-with-byte-buddy
• Cglib Github https://github.com/cglib/cglib
• Cglib Enhancer https://cglib.sourceforge.net/apidocs/net/sf/cglib/proxy/Enhancer.html

Let Kotlin do the code for you — Part III: Mockito, Mockk, and Code Generation was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to code libraries that your iOS teammates will not frown upon using them. This is the final chapter: Flow!

I know you have been waiting long for the Great Season Finale of this series: Flow! Let us see if we can apply what we learned so far.

This article is part of a series, see the other articles here

I will use the most classical example: a flow that every second emits a value. In this case, I am using kotlinx-datetime, the official multiplatform library for time.

// KOTLIN API CODE
class Clock {
    fun ticker(): Flow<String> = flow {
        while (currentCoroutineContext().isActive) {
            val now: Instant = Clock.System.now()
            val thisTime: LocalTime = now.toLocalDateTime(TimeZone.currentSystemDefault()).time
            emit(thisTime.toString())
            delay(1_000)
        }
    }
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Watch")))
@interface SharedWatch : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
- (id<SharedKotlinx_coroutines_coreFlow>)ticker __attribute__((swift_name("ticker()")));
@end

__attribute__((swift_name("Kotlinx_coroutines_coreFlow")))
@protocol SharedKotlinx_coroutines_coreFlow
@required

/**
 * @note This method converts instances of CancellationException to errors.
 * Other uncaught Kotlin exceptions are fatal.
*/
- (void)collectCollector:(id<SharedKotlinx_coroutines_coreFlowCollector>)collector completionHandler:(void (^)(NSError * _Nullable))completionHandler __attribute__((swift_name("collect(collector:completionHandler:)")));
@end

__attribute__((swift_name("Kotlinx_coroutines_coreFlowCollector")))
@protocol SharedKotlinx_coroutines_coreFlowCollector
@required

/**
 * @note This method converts instances of CancellationException to errors.
 * Other uncaught Kotlin exceptions are fatal.
*/
- (void)emitValue:(id _Nullable)value completionHandler:(void (^)(NSError * _Nullable))completionHandler __attribute__((swift_name("emit(value:completionHandler:)")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class Watch : KotlinBase {
    public init()
    open func ticker() -> Kotlinx_coroutines_coreFlow
}

public protocol Kotlinx_coroutines_coreFlow {
    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    func collect(collector: Kotlinx_coroutines_coreFlowCollector, completionHandler: @escaping (Error?) -> Void)

    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    func collect(collector: Kotlinx_coroutines_coreFlowCollector) async throws
}

public protocol Kotlinx_coroutines_coreFlowCollector {
    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    func emit(value: Any?, completionHandler: @escaping (Error?) -> Void)

    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    func emit(value: Any?) async throws
}

So what happened to our beautiful KMP API? In Part VIII we saw that Kotlin Interfaces are exported as Objective-C Protocols, which do not support Generics. Consequently, the type argument String is lost. The collect function is a suspend method, and as we saw in Part VII it will be exported to Objective-C as a function with a completion handler. Additionally, thanks to Xcode bridging, it will also feature an async version for Swift.

Although the API is somewhat usable, our Swift teammate will have two major inconveniences:

• Because the Generic type information is lost, the Swift developer will have to forcibly cast (as!) every flow emission from Any? to String;
• There is no way to cancel our infinite flow.

With all those problems, how can we convince iOS developers that KMP is a good idea?

A Solution

Based on the last two chapters of this series we know that a solution will require two things:

1. We must return a class because Kotlin classes are exported as Objective-C classes, the only type that really supports generics;
2. We need to create a wrapper for Flow that works like a handle, having one method to start the flow and another to cancel it.

FlowWrapper as the name says will work as our handle class. The constructor will receive the flow to be wrapped and the coroutine scope that we want to use for the collection. Its collect method will follow the same pattern as all other solutions that I saw for flows. It will have a very “ReactiveX” signature with an onEach callback for emissions and an onComplete callback for errors and completion. In fact, most solutions that I saw name such method subscribe.

In the iosMain sourceset we create the extension Watch.wrappedTicker and we use @ObjCName(“ticker”) on it and @HiddenFromObjC on the original method to effectively replace it with the wrapped version for iOS.

// KOTLIN API CODE
class Watch {
    @OptIn(ExperimentalObjCRefinement::class)
    @HiddenFromObjC // Will not be exported to Obj-C and Swift
    fun ticker(): Flow<String> = flow {
        while (currentCoroutineContext().isActive) {
            val now: Instant = Clock.System.now()
            val thisTime: LocalTime = now.toLocalDateTime(TimeZone.currentSystemDefault()).time
            emit(thisTime.toString())
            delay(1_000)
        }
    }
}

class FlowWrapper<out T> internal constructor(private val scope: CoroutineScope,
                                              private val flow: Flow<T & Any>){
    private var job: Job? = null
    private var isCancelled = false

    /**
     *  Cancels the flow
     */
    fun cancel() {
        isCancelled = true
        job?.cancel()
    }

    /**
     * Starts the flow
     * @param onEach callback called on each emission
     * @param onCompletion callback called when flow completes. It will be provided with a non
     * nullable Throwable if it completes abnormally
     */
    fun collect(
        onEach: (T & Any) -> Unit,
        onCompletion: (Throwable?) -> Unit
    ) {
        if (isCancelled) return
        job = scope.launch {
            flow.onEach(onEach).onCompletion { cause: Throwable? -> onCompletion(cause) }.collect()
        }
    }
}

internal fun <T> Flow<T&Any>.wrap(scope: CoroutineScope = MainScope()) = FlowWrapper(scope, this)

// iosMain
@ObjCName("ticker")
fun Watch.wrappedTicker() = this.ticker().wrap()

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Watch")))
@interface SharedWatch : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("FlowWrapper")))
@interface SharedFlowWrapper<__covariant T> : SharedBase
- (void)cancel __attribute__((swift_name("cancel()")));
- (void)collectOnEach:(void (^)(T))onEach onCompletion:(void (^)(SharedKotlinThrowable * _Nullable))onCompletion __attribute__((swift_name("collect(onEach:onCompletion:)")));
@end

@interface SharedWatch (Extensions)
- (SharedFlowWrapper<NSString *> *)ticker __attribute__((swift_name("ticker()")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class Watch : KotlinBase {
    public init()
}

public class FlowWrapper<T> : KotlinBase where T : AnyObject {
    open func cancel()
    open func collect(onEach: @escaping (T) -> Void, onCompletion: @escaping (KotlinThrowable?) -> Void)
}

extension Watch {
    open func ticker() -> FlowWrapper<NSString>
}

Now our Swift colleague can not only collect the flow but also be notified that it has been completed and cancel it.

// SWIFT CLIENT CODE
func test() {
    let watch = Watch()
    let handle = watch.ticker()
    handle.collect {
        value in print(value)
    } onCompletion: { throwable in
        print("Complete : \(throwable?.description() ?? "<Success>")")
    }

    DispatchQueue.main.asyncAfter(deadline: .now() + 10){
        print("CANCELLING")
        handle.cancel()
    }
}

But can we make our iOS dev colleague feel more at home?

Being more “Swifty”: Supporting Combine

In the same way, we Android developers are moving from RxJava to Flows, Swift developers are moving from RxSwift to Combine — Apple’s implementation of reactive streams.

However, Combine is a pure Swift Framework and consequently, it is not accessible from Objective-C. In that case, we learned in Part IV that in those cases we need to get our hands dirty and write a Swift extension to fill the gaps in our API. Let’s do it then!

First, we extend KotlinThrowable — the exported version of Throwable — to conform to the Error protocol so we can forward any exceptions on our flow. Second, we need to implement a Publisher that will wrap our wrapper to our flow (“We can solve any problem by introducing an extra level of indirection.”). Combine is based on the Publisher-Subscriber paradigm. This sequence diagram gives us a good idea of how those two interact:

Next, our publisher defines the Associated Types for the Publisher protocol by setting Output to our generic type argument and Failure to KotlinThrowable. Then, we need to implement the method receive, which will have to follow the sequence depicted in the diagram above:

1. Calls Subscriber::receive(subscription:)to pass a Subscription object. We have created FlowSubscription, which conforms to the Subscription protocol, so we can relay the subscription cancellation requests to our flow;
2. Call Subscriber::receive(_ input:) to forward the elements emitted by the flow;
3. Finally, call Subscriber::receive(completion:) when the flow ends either normally (Subscribers.Completion::finished) or with failure (Subscriber.Completion::failure(Failure))

import Combine

extension KotlinThrowable: Error {}

class FlowPublisher<T: AnyObject>: Publisher {
    typealias Output = T
    typealias Failure = KotlinThrowable
    
    private let wrappedFlow: FlowWrapper<T>
    
    init(wrappedFlow: FlowWrapper<T>) {
        self.wrappedFlow = wrappedFlow
    }
    
    func receive<S>(subscriber: S) where S : Subscriber, KotlinThrowable == S.Failure, T == S.Input {
        let subscription = FlowSubscription(wrappedFlow: wrappedFlow)
        
        subscriber.receive(subscription: subscription)
        
        wrappedFlow.collect { value in
           let demand: Subscribers.Demand = subscriber.receive(value)
           // Dealing with demand is left as exercise for the reader
        } onCompletion: { throwable in
            subscriber.receive(completion: throwable == nil ? .finished : .failure(throwable!))
        }
    }
    
    class FlowSubscription: Subscription {
        
        private let wrappedFlow: FlowWrapper<T>
        
        init(wrappedFlow: FlowWrapper<T>) {
            self.wrappedFlow = wrappedFlow
        }
        
        func request(_ demand: Subscribers.Demand) {
            // Dealing with demand is left as exercise for the reader
        }
        
        //Progates the cancel 
        func cancel() {
            wrappedFlow.cancel()
        }
    }
}

func flow<T>(_ wrapper: FlowWrapper<T>) -> FlowPublisher<T> {
    return FlowPublisher(wrappedFlow: wrapper)
}

The flow above is a helper function to wrap our wrapper. Now Swift devs can consume our flow in a more familiar way:

func test() {
    let watch = Watch()
    let handle = flow(watch.ticker())
        .handleEvents(receiveSubscription: { _ in print("Subscribed") },
                      receiveCancel: { print("Cancelled") })
        .sink(receiveCompletion: { completion in switch completion {
        case .finished:
            print("Completed with success")
            break
        case let .failure(throwable):
            print("Completed with failure: \(throwable)")
            break
        }}, receiveValue: { value in print(value) })
    
    DispatchQueue.main.asyncAfter(deadline: .now() + 10){
        print("CANCELLING")
        handle.cancel()
    }
}

Subscribers.Demand is the Combine way to deal with backpressure.

KMP-NativeCoroutines

Of course, like for coroutines, people already created libraries so you do not have to learn Swift. The libraries that I cited in Part VII, SKIE, Koru, and KMP-NativeCoroutines also support Flows. Again, let us see how we can use KMP-NativeCoroutines with our example.

Usage is very similar to coroutines. We use the @NativeCoroutineScope annotation to denote the scope that we want to use to collect the flows. Again @NativeCoroutines will hide our original method, and during the annotation processing phase by KSP it will provoke the generation of the replacement extension Watch.tickerNative().

// KOTLIN API CODE
@NativeCoroutineScope
internal val coroutineScope = MainScope()

class Watch {
    @NativeCoroutines
    fun ticker(): Flow<String> = flow {
        while (currentCoroutineContext().isActive) {
            val now: Instant = Clock.System.now()
            val thisTime: LocalTime = now.toLocalDateTime(TimeZone.currentSystemDefault()).time
            emit(thisTime.toString())
            delay(1_000)
        }
    }
}

// ios* CODE GENERATED BY KSP
@ObjCName(name = "ticker")
public fun Watch.tickerNative(): NativeFlow<String> = ticker().asNativeFlow(coroutineScope)

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Watch")))
@interface SharedWatch : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
@end

@interface SharedWatch (Extensions)
- (SharedKotlinUnit *(^(^)(SharedKotlinUnit *(^)(NSString *, SharedKotlinUnit *(^)(void), SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError * _Nullable, SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError *, SharedKotlinUnit *)))(void))ticker __attribute__((swift_name("ticker()")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class Watch : KotlinBase {
    public init()
}

extension Watch {
    open func ticker() -> (@escaping (String, @escaping () -> KotlinUnit, KotlinUnit) -> KotlinUnit, @escaping (Error?, KotlinUnit) -> KotlinUnit, @escaping (Error, KotlinUnit) -> KotlinUnit) -> () -> KotlinUnit
}

In a similar way to our solution, we need to use createPublisher(for:) to wrap the flow into a publisher.

import KMPNativeCoroutinesCombine

func test() {
    let watch = Watch()
    let publisher = createPublisher(for: watch.ticker())
    let handle = publisher
        .handleEvents(receiveSubscription: { _ in print("Subscribed") },
                      receiveCancel: { print("Cancelled") })
        .sink(receiveCompletion: { completion in switch completion {
        case .finished:
            print("Completed with success")
            break
        case let .failure(throwable):
            print("Completed with failure: \(throwable)")
            break
        }}, receiveValue: { value in print(value) })
    
    DispatchQueue.main.asyncAfter(deadline: .now() + 10){
        print("CANCELLING")
        handle.cancel()
    }
}

And this is the end! C’est la fin!

Now you can appreciate the entire series at once:

Writing Swift-friendly Kotlin Multiplatform APIs

Ci vediamo a Torino! See y’all at London!

As usual, every June I attend Droidcon San Francisco. As I got my seat for one of the first talks, I started hearing some Portuguese. I learned it was a group of Brazilian compatriots who work in Europe and they came to Droidcon SF as speakers. After we exchanged our experiences of working in Europe and Silicon Valley, they really convinced me to be a speaker as well.

Even though I am a frequent attendant of conferences and meetups in the Bay Area, I have never given a talk since I moved here in 2014. The reason for that can be attributed to Impostor Syndrome due to a non-helping work environment, and perhaps some Stockholm Syndrome as well 😅. As preparation, I started writing this very series. At that time I was working mostly with Compose and KMP.

The first conference that accepted my talk was Droidcon Italy. Italy is special to me. If Brazil is my motherland, Italy is my grandmotherland. I am a third-generation Venetian and a fourth-generation Lombardian. Once you move to the US, the most common question you get is “Where are you from?”, and you hear it so often — even people who were born here — that one starts questioning oneself. Result: I learned Italian for two years and last year my Italian citizenship by descent was officially recognized.

And I just got an email telling me that my talk was also accepted by Droidcon London.

Droidcon Italy will be held on October 12th-13th in Turin, Piedmont, Italy at the Museo Nazionale dell’Automobile. Fun fact: I have been to Turin once in 2018. The very day I planned to visit the museum, it was closed. Now I am going to be speaking at it.

Droidcon London will be held on October 26th-27th in London, UK at the Business Design Centre

The nice thing about those conferences is that they are on the other side of the Atlantic. If my talk is really bad, the news will have to cross the ocean 🙂. The bad news is that it is going to be a hella expensive journey 😞.

Acknowledgment

• Thomas Hultgreen, Daniel Youn, Marquis Kurt: coworkers that mainly helped me with advanced Swift topics;
• Paolo Rotolo, John O’Reilly, and Pamela Hill: people who already talked about KMP in the past, helped me on topics that I have not worked on, and spontaneously spread my articles;
• Better Programming, Towards Dev, and ProAndroidDev that published the articles in this series;
• Android Weekly and Kotlin Weekly that featured my articles.

References

• BUI, Dui — How to Implement MVVM with Combine in SwiftUI https://iosapptemplates.com/blog/swiftui/mvvm-combine-swiftui
• Apple documentation — Publisher https://developer.apple.com/documentation/combine/publisher
• Apple documentation — Subscriber https://developer.apple.com/documentation/combine/subscriber
• Apple documentation — Subscription https://developer.apple.com/documentation/combine/subscription
• Apple documentation — Subscribers.Demand https://developer.apple.com/documentation/combine/subscribers/demand
• GARDNER, Scott — Publishers & Subscribers https://www.kodeco.com/books/combine-asynchronous-programming-with-swift/v2.0/chapters/2-publishers-subscribers
• HUDSON, Paul — Understanding protocol associated types and their constraints https://www.hackingwithswift.com/articles/74/understanding-protocol-associated-types-and-their-constraints
• O’REILLY, John — Wrapping Kotlin Flow with Swift Combine Publisher in a Kotlin Multiplatform project https://johnoreilly.dev/posts/kotlinmultiplatform-swift-combine_publisher-flow/
• BRANCATI, Fabrizio — Combine: Getting Started https://www.kodeco.com/7864801-combine-getting-started

Writing Swift-friendly Kotlin Multiplatform APIs — Part IX: Flow was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Let’s create a Compose Button from scratch and apply Separation of Concerns.

Design Language Systems are becoming an increasing trend among Mobile designers. Your lovely designer follows such a trend and provides you with the below specifications for buttons. They are not really Material buttons. They do not use elevation changes or ripples. Reusing a Material button would require us to manually disable such features, which is bug-prone and may require maintenance on each Compose update. You then decide to implement a button from scratch. How would you go about it?

You might be tempted at first to write a single and huge Composable function that implements the button and encompasses all of its aspects. That might result in very complex code that will be pretty hard to maintain. Is there a structured way in which we can implement the button?

When implementing the button we have four major concerns:

1. We need to draw the button;
2. The way we draw the button will change according to the animation parameters;
3. Animations are triggered in response to state changes;
4. We should be able to customize the representation of the different states of a button;

Could we implement each of those concerns in an independent way? Looks like each concern affects the other. Could we arrange them in a pipeline so all the data flows among them in a single direction as required by Compose? That is what I am proposing here:

Each concern will be a stage in our data pipeline. Let’s describe each stage.

Drawing

In the drawing stage, our only concern is ensuring we correctly draw the button. Everything like colors, sizes, and text styles are passed as parameters so it can be affected by the upper stages.

The Compose naming conventions say “MUST name any function that returns Unit and bears the @Composable annotation using PascalCase, and the name MUST be that of a noun”. However, I will be breaking them for the name of a @Composable function that implements a stage, using camelCase instead of PascalCase. The rationale for that is that those functions do not implement a full and self-sufficient Component, whose View counterpart would be a class, and hence the usage of PascalCase. Those functions are more like methods of a class with very well-defined objectives that together will build the component. Hence camelCase like it is for any method of a class. Besides they are file private and they will not be part of the public API.

@SuppressLint("ComposableNaming")
@Composable
private fun drawButton(
    text: String,
    icon: ImageVector?,
    backgroundColor: Color,
    foregroundColor: Color,
    borderColor: Color,
    shape: Shape,
    iconSize: Dp,
    borderSize: Dp,
    spacing: Dp,
    minWidth: Dp,
    minHeight: Dp,
    paddings: PaddingValues,
    textStyle: TextStyle,
    modifier: Modifier = Modifier
) {
    Row(
        verticalAlignment = Alignment.CenterVertically,
        horizontalArrangement = Arrangement.Center,
        modifier = modifier
            .border(
                width = borderSize,
                color = borderColor,
                shape = shape
            )
            .background(
                color = backgroundColor,
                shape = shape
            )
            .padding(paddings)
            .defaultMinSize(minWidth = minWidth, minHeight = minHeight)
    ) {
        if (icon != null) {
            Icon(
                imageVector = icon,
                contentDescription = null,
                tint = foregroundColor,
                modifier = Modifier.size(iconSize)
            )
            Spacer(modifier = Modifier.width(spacing))
        }
        Text(text = text, color = foregroundColor, style = textStyle)
    }
}

We can then write several previews for drawButton to verify the rendering for various situations like when the button has no icon, the text is very long, or even when it is used with RTL scripts like the old Phoenician alphabet.

Animation

This is the second lowest stage in the pipeline and it is responsible for setting up the animations. You can clearly see that animateButton is organized into three sections:

1. Receiving parameters: some will be used by the animations, others will pass through reaching the drawing stage;
2. Setting up animations: in this case, we want to animate the colors and content size changes in case the text changes or whenever we hide or show the icon;
3. Passing data to the next stage in the pipeline.

@SuppressLint("ComposableNaming")
@Composable
private fun animateButton(
    text: String,
    icon: ImageVector?,
    backgroundColor: Color,
    foregroundColor: Color,
    borderColor: Color,
    shape: Shape,
    iconSize: Dp,
    borderSize: Dp,
    spacing: Dp,
    minWidth: Dp,
    minHeight: Dp,
    paddings: PaddingValues,
    textStyle: TextStyle,
    animationDuration: Int,
    animationEasing: Easing,
    modifier: Modifier = Modifier
) {
    val colorAnimationSpec =
        tween<Color>(durationMillis = animationDuration, easing = animationEasing)
    val animatedBorderColor by animateColorAsState(
        animationSpec = colorAnimationSpec,
        targetValue = borderColor,
        label = "border"
    )
    val animatedBackgroundColor by animateColorAsState(
        animationSpec = colorAnimationSpec,
        targetValue = backgroundColor,
        label = "background"
    )
    val animatedForegroundColor by animateColorAsState(
        animationSpec = colorAnimationSpec,
        targetValue = foregroundColor,
        label = "foreground"
    )

    val localModifier = modifier.animateContentSize(
        animationSpec = tween(
            durationMillis = animationDuration,
            easing = animationEasing
        )
    )
    drawButton(
        text = text,
        icon = icon,
        backgroundColor = animatedBackgroundColor,
        foregroundColor = animatedForegroundColor,
        borderColor = animatedBorderColor,
        shape = shape,
        iconSize = iconSize,
        borderSize = borderSize,
        spacing = spacing,
        minWidth = minWidth,
        minHeight = minHeight,
        paddings = paddings,
        textStyle = textStyle,
        modifier = localModifier
    )
}

Luckily again, Compose preview tooling can help us verify if we are on the right track. Note that setting the labels for the animations in the code above became really handy with the Animation Preview, where one can pick any colors he or she wants for the tests.

State

This stage will manage the button state: when it is pressed, clicked, focused, and whatnot, and the consequences to other parameters such as the colors. It is very loosely inspired by the Material Button implementation.

The number of parameters in the stages is growing considerably. To tidy things up let's create some data structures to group them.

object ButtonInteractionState {
    @JvmStatic
    val HOVER = 1.shl(0)

    @JvmStatic
    val PRESSED = 1.shl(1)

    @JvmStatic
    val FOCUSED = 1.shl(2)
}

interface ButtonColors {
    @Stable
    @Composable
    fun borderColor(interactionState: Int, enabled: Boolean): State<Color>

    @Stable
    @Composable
    fun foregroundColor(interactionState: Int, enabled: Boolean): State<Color>

    @Stable
    @Composable
    fun backgroundColor(interactionState: Int, enabled: Boolean): State<Color>
}

@Immutable
interface ButtonSizes {
    val iconSize: Dp
    val borderSize: Dp
    val contentPadding: PaddingValues
    val spacing: Dp
    val minWidth: Dp
    val minHeight: Dp
}

@Immutable
interface ButtonAnimation {
    val duration: Int
    val easing: Easing
}

ButtonInteractionState defines constants in a bitfield manner because a button can focused, hovered, and pressed, all at the same time.

ButtonColors defines the signature for methods that will give the color to be used with the current button state provided by the parameters. The @Stable annotation tells the Compose compiler that those functions will return the same result if the same parameters are passed in, so it can do some optimizations.

I believe that ButtonSizes and ButtonAnimation are self-explanatory.

Similarly to animateButton, stateButton is divided into sections:

1. Figuring out the current state using the interaction source;
2. Defining our button as clickable, and passing the enabled state and the onClick callback;
3. Calculating the colors to be used according to the state

There are some important things to note when setting the clickable modifier:

• We are forwarding the MutableInteractionSource;
• We are not using Indication;
• We set the role to Role.Button, which will help Compose accessibility, focus management, etc.

Discussing Indication is out of the scope of this article. Indication “represents visual effects that occur when certain interactions happen”. For instance, the Surface component always sets the characteristic Material ripple effect using Indication. For a really deep dive into Interaction Sources and Indication read this article published in Android Developers.

@SuppressLint("ComposableNaming")
@Composable
private fun stateButton(
    text: String,
    onClick: () -> Unit,
    icon: ImageVector?,
    colors: ButtonColors,
    sizes: ButtonSizes,
    shape: Shape,
    textStyle: TextStyle,
    animation: ButtonAnimation,
    modifier: Modifier = Modifier,
    enabled: Boolean = true,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() }
) {
    val isHovered by interactionSource.collectIsHoveredAsState()
    val isPressed by interactionSource.collectIsPressedAsState()
    val isFocused by interactionSource.collectIsFocusedAsState()

    var interactionState = 0
    if (isHovered) interactionState = interactionState.or(ButtonInteractionState.HOVER)
    if (isPressed) interactionState = interactionState.or(ButtonInteractionState.PRESSED)
    if (isFocused) interactionState = interactionState.or(ButtonInteractionState.FOCUSED)

    val currentModifier = modifier.clickable(
        interactionSource = interactionSource,
        indication = null,
        enabled = enabled,
        onClick = onClick
    )

    val backgroundColor = colors.backgroundColor(interactionState, enabled).value
    val foregroundColor = colors.foregroundColor(interactionState, enabled).value
    val borderColor = colors.borderColor(interactionState, enabled).value
    
    animateButton(
        text = text,
        icon = icon,
        backgroundColor = backgroundColor,
        foregroundColor = foregroundColor,
        borderColor = borderColor,
        shape = shape,
        iconSize = sizes.iconSize,
        borderSize = sizes.borderSize,
        spacing = sizes.spacing,
        minWidth = sizes.minWidth,
        minHeight = sizes.minHeight,
        paddings = sizes.contentPadding,
        textStyle = textStyle,
        animationDuration = animation.duration,
        animationEasing = animation.easing,
        modifier = currentModifier
    )
}

Theming

In this stage, we are finally implementing the specifications given by our designer. Considering that we are using a custom font, Monstserrat, we need to define a FontFamily:

val MontserratFont = FontFamily(
    Font(R.font.montserrat_thin, weight = FontWeight.Thin, style = FontStyle.Normal),
    Font(R.font.montserrat_thin_italic, weight = FontWeight.Thin, style = FontStyle.Italic),
    Font(R.font.montserrat_extra_light, weight = FontWeight.ExtraLight, style = FontStyle.Normal),
    Font(R.font.montserrat_extra_light_italic, weight = FontWeight.ExtraLight, style = FontStyle.Italic),
    Font(R.font.montserrat_light, weight = FontWeight.Light, style = FontStyle.Normal),
    Font(R.font.montserrat_light_italic, weight = FontWeight.Light, style = FontStyle.Italic),
    Font(R.font.montserrat_regular, weight = FontWeight.Normal, style = FontStyle.Normal),
    Font(R.font.montserrat_italic, weight = FontWeight.Normal, style = FontStyle.Italic),
    Font(R.font.montserrat_medium, weight = FontWeight.Medium, style = FontStyle.Normal),
    Font(R.font.montserrat_medium_italic, weight = FontWeight.Medium, style = FontStyle.Italic),
    Font(R.font.montserrat_semi_bold, weight = FontWeight.SemiBold, style = FontStyle.Normal),
    Font(R.font.montserrat_semi_bold_italic, weight = FontWeight.SemiBold, style = FontStyle.Italic),
    Font(R.font.montserrat_bold, weight = FontWeight.Bold, style = FontStyle.Normal),
    Font(R.font.montserrat_bold_italic, weight = FontWeight.Bold, style = FontStyle.Italic),
    Font(R.font.montserrat_extra_bold, weight = FontWeight.ExtraBold, style = FontStyle.Normal),
    Font(R.font.montserrat_extra_bold_italic, weight = FontWeight.ExtraBold, style = FontStyle.Italic),
    Font(R.font.montserrat_black, weight = FontWeight.Black, style = FontStyle.Normal),
    Font(R.font.montserrat_black_italic, weight = FontWeight.Black, style = FontStyle.Italic),
)

In ui.theme.Colors we define constants for the colors we will use:

val ButtonBorderFocused = Color(0xFF00FFFF)
val ButtonBorderNormal = Color(0xFF1C4587)
val ButtonForegroundNormal = Color.White
val ButtonForegroundHovered = Color(0xFF1C4587)
val ButtonForegroundDisabled = Color(0xFF666666)
val ButtonBackgroundNormal = Color(0XFF3C78D8)
val ButtonBackgroundHovered = Color(0xFFC9DAF8)
val ButtonBackgroundPressed = Color(0xFF1C4587)
val ButtonBackgroundDisabled = Color(0xFFEFEFEF)

ObjectDefaults will group all the specs together into a single object:

private infix fun Int.has(bit: Int) = this.and(bit) != 0

object ButtonDefaults {
    val colors = object : ButtonColors {
        @Composable
        override fun borderColor(interactionState: Int, enabled: Boolean): State<Color> {
            return rememberUpdatedState(
                when {
                    !enabled -> ButtonForegroundDisabled
                    interactionState has ButtonInteractionState.FOCUSED -> ButtonBorderFocused
                    interactionState has ButtonInteractionState.HOVER -> ButtonForegroundHovered
                    else -> ButtonBorderNormal
                }
            )
        }

        @Composable
        override fun foregroundColor(interactionState: Int, enabled: Boolean): State<Color> {
            return rememberUpdatedState(
                when {
                    !enabled -> ButtonForegroundDisabled
                    interactionState has ButtonInteractionState.HOVER -> ButtonForegroundHovered
                    else -> ButtonForegroundNormal
                }
            )
        }

        @Composable
        override fun backgroundColor(interactionState: Int, enabled: Boolean): State<Color> {
            return rememberUpdatedState(
                when {
                    !enabled -> ButtonBackgroundDisabled
                    interactionState has ButtonInteractionState.PRESSED -> ButtonBackgroundPressed
                    interactionState has ButtonInteractionState.HOVER -> ButtonBackgroundHovered
                    else -> ButtonBackgroundNormal
                }
            )
        }
    }

    val sizes = object : ButtonSizes {
        override val iconSize = 32.dp
        override val borderSize = 3.dp
        override val contentPadding = PaddingValues(all = 16.dp)
        override val spacing = 8.dp
        override val minWidth = 60.dp
        override val minHeight = 48.dp

    }

    val animation = object : ButtonAnimation {
        override val duration = 250
        override val easing = EaseInCirc
    }

    val shape = CutCornerShape(topEndPercent = 30, bottomStartPercent = 30)

    val textStyle = TextStyle(
        fontFamily = MontserratFont,
        fontWeight = FontWeight.SemiBold,
        fontSize = 24.sp
    )
}

Putting everything together

We can now finally put everything together and create our Button component. We use the specs defined in ButtonDefaults as our default values, so we still allow some local customization:

@Composable
fun Button(
    text: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier,
    icon: ImageVector? = null,
    enabled: Boolean = true,
    colors: ButtonColors = ButtonDefaults.colors,
    sizes: ButtonSizes = ButtonDefaults.sizes,
    shape: Shape = ButtonDefaults.shape,
    textStyle: TextStyle = ButtonDefaults.textStyle,
    animation: ButtonAnimation = ButtonDefaults.animation,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() }
) {
    stateButton(
        text,
        onClick,
        icon,
        colors,
        sizes,
        shape,
        textStyle,
        animation,
        modifier,
        enabled,
        interactionSource
    )
}

Let’s write some previews:

Enabled state

@Preview(name = "Enabled", group = "Button", showBackground = true)
@Composable
fun ButtonPreview() {
    ComposeButtonTheme {
        var showIcon by remember { mutableStateOf(true) }
        Box(modifier = Modifier.padding(24.dp)) {
            Button(
                text = "Button Text",
                onClick = { showIcon = !showIcon },
                icon = if (showIcon) Icons.Default.Home else null
            )
        }
    }
}

Disabled State

@Preview(name = "Disabled", group = "Button", showBackground = true)
@Composable
fun ButtonDisabledPreview() {
    ComposeButtonTheme {
        var showIcon by remember { mutableStateOf(true) }
        Box(modifier = Modifier.padding(24.dp)) {
            Button(
                text = "Button Text",
                onClick = { showIcon = !showIcon },
                icon = if (showIcon) Icons.Default.Home else null,
                enabled = false
            )
        }
    }
}

Source Code

The entire source code for this article is available at:

https://github.com/aoriani/ComposeButton

References

• Material Compose Button source code https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:compose/material/material/src/commonMain/kotlin/androidx/compose/material/Button.kt
• Stable | Android Developers https://developer.android.com/reference/kotlin/androidx/compose/runtime/Stable
• PULLEN-FREILICH, Louis — Illuminating Interactions: Visual State in Jetpack Compose in Android Developers https://medium.com/androiddevelopers/illuminating-interactions-visual-state-in-jetpack-compose-188fa041b791
• ULANOVSKY, Julia — Montserrat Font https://fonts.google.com/specimen/Montserrat/about?query=Mont
  https://github.com/JulietaUla/Montserrat
• API Guidelines for Jetpack Compose https://github.com/androidx/androidx/blob/androidx-main/compose/docs/compose-component-api-guidelines.md

Compose a Compose Button by composing Composable functions was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to code libraries that your iOS teammates will not frown upon using them. In this chapter: generics

My initial plan was that an article on Flows would follow the chapter about Coroutines, and then I would close the series with Generics. However, I realized that I needed first to talk about Generics. After all, Flow, StateFlow, and SharedFlow are generics types. Therefore understanding the limitations around the translation of Kotlin Generics to Objective-C, and by extension Swift, will be the basis to comprehend the solutions for using Flows in Swift.

This article is part of a series, see the other articles here

Lightweight Generics in Objective-C

Objective-C did neither have nullability nor Generic types until WWDC 2015. Both were introduced with the goal of improving the interoperability between Objective-C and Swift. In the case of Generics, the focus was to provide typed collections. Prior to Lightweight Generics, collection types such as NSArray, NSSet, and NSDictionary were bridged to Swift Lists, Sets, and Dictionaries of AnyObject. Now it was possible to specify the exact contained type, so, for example, an instance of NSArray<NSString *> could be mapped to [String] (a list of String). They are called lightweight because they rely on type erasure and do not require changes to Objective-C runtime.

In this article, I will try several examples of Generics interoperability between Kotlin and Swift and analyze whether the translation maintains the nullability, variance, and bounds originally defined in the Kotlin code.

As a complement to this article, I recommend the following readings:

• Kevin Galligan’s Kotlin Native Interop Generics article, which provides insight into the decisions behind the implementation of the interop;
• Kotlin/Multiplatform for iOS developers: state & future, KotlinConf 2023 lecture by Salomon BRYS, which presents a relatively complex example of Generics interop.

Classes

Kotlin Classes are mapped to Objective-C classes, the only type really supported by Lightweight Generics.

Nullability

// KOTLIN API CODE
class GenericClass<T>(val value: T)
class GenericClassNonNullable<T: Any>(val value: T)

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("GenericClass")))
@interface SharedGenericClass<T> : SharedBase
- (instancetype)initWithValue:(T _Nullable)value __attribute__((swift_name("init(value:)"))) __attribute__((objc_designated_initializer));
@property (readonly) T _Nullable value __attribute__((swift_name("value")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("GenericClassNonNullable")))
@interface SharedGenericClassNonNullable<T> : SharedBase
- (instancetype)initWithValue:(T)value __attribute__((swift_name("init(value:)"))) __attribute__((objc_designated_initializer));
@property (readonly) T value __attribute__((swift_name("value")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class GenericClass<T> : KotlinBase where T : AnyObject {
    public init(value: T?)
    open var value: T? { get }
}

public class GenericClassNonNullable<T> : KotlinBase where T : AnyObject {
    public init(value: T)
    open var value: T { get }
}

// SWIFT CLIENT CODE
func nullabilityTest() {
    class Person {
        let firstName: String
        let lastName: String
        init(firstName fn: String, lastName ln: String) {
            firstName = fn
            lastName = ln
        }
    }
    let willSmith = Person(firstName: "Will", lastName: "Smith")
    
    let a: Person = GenericClass<Person>(value: willSmith).value!
    let b: Person = GenericClassNonNullable<Person>(value: willSmith).value
}

From the above, we see that unless you bound your generic type to a non-nullable type like Any, Kotlin we will assume the worst case and set the type as nullable since it does not have control over how it is going to be used in Swift. Your Swift developer will be forced to unwrap.

Another thing to notice is that in Swift our generic type is bound to AnyObject. AnyObject is the Kotlin equivalent of Any and Java’s Object. Any in Swift is a broader super type, including support to not only objects of classes but instances of structs, enums, protocols, function types, and really anything else. Therefore we cannot have GenericClass<String> because in Swift, String is a struct.

Variance

// KOTLIN API CODE
class GenericClassCovariant<out T>(val value: T)
class GenericClassContravariant<in T>(val value: Int)

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("GenericClassCovariant")))
@interface SharedGenericClassCovariant<__covariant T> : SharedBase
- (instancetype)initWithValue:(T _Nullable)value __attribute__((swift_name("init(value:)"))) __attribute__((objc_designated_initializer));
@property (readonly) T _Nullable value __attribute__((swift_name("value")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("GenericClassContravariant")))
@interface SharedGenericClassContravariant<__contravariant T> : SharedBase
- (instancetype)initWithValue:(int32_t)value __attribute__((swift_name("init(value:)"))) __attribute__((objc_designated_initializer));
@property (readonly) int32_t value __attribute__((swift_name("value")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class GenericClassCovariant<T> : KotlinBase where T : AnyObject {
    public init(value: T?)
    open var value: T? { get }
}

public class GenericClassContravariant<T> : KotlinBase where T : AnyObject {
    public init(value: Int32)
    open var value: Int32 { get }
}

Variance for Lightweight Generics is an interesting case. From the code above we do see that out and in in Kotlin are mapped to the __covariant and __contravariant annotations in Objective-C. In the test below we do see that the variance works in Objective-C and the expected assignments are allowed.

// OBJ-C CLIENT CODE
#import <Foundation/Foundation.h>
#import <shared/shared.h>

void objc_variant_test(void)
{
    SharedGenericClass<SharedInt *> *a = [[SharedGenericClass alloc] initWithValue: @1];
    // Warning: Incompatible pointer types initializing 'SharedGenericClass<SharedNumber *> *'
    // with an expression of type 'SharedGenericClass<SharedInt *> *'
    SharedGenericClass<SharedNumber*> *b = a;
    
    SharedGenericClassCovariant<SharedInt *> *c = [[SharedGenericClassCovariant alloc] initWithValue: @1];
    // No Warnings
    SharedGenericClassCovariant<SharedInt *> *d = c;
    
    SharedGenericClassContravariant<SharedNumber *> *f = [[SharedGenericClassContravariant alloc] initWithValue: 1];
    // No Warnings
    SharedGenericClassContravariant<SharedInt *> *g = f;
}

But, surprisingly variance is lost in translation during the bridging to Swift, and the assignments between super and sub classes become illegal. You can force-cast with as!, but type safety checks will be nonexistent.

// SWIFT CLIENT CODE
func swiftVariantTest() {
    let a: GenericClass<KotlinInt> = GenericClass(value: 1)
    //Error: Cannot assign value of type 'GenericClass<KotlinInt>' to type 'GenericClass<KotlinNumber>'
    let b: GenericClass<KotlinNumber> = a

    let c: GenericClassCovariant<KotlinInt> = GenericClassCovariant(value: 1)
    //Error: Cannot assign value of type 'GenericClassCovariant<KotlinInt>' to type 'GenericClassCovariant<KotlinNumber>'
    let d: GenericClassCovariant<KotlinNumber> = c

    let e: GenericClassContravariant<KotlinNumber> = GenericClassContravariant(value: 1)
    //Error: Cannot assign value of type 'GenericClassContravariant<KotlinNumber>' to type 'GenericClassContravariant<KotlinInt>'
    let f: GenericClassContravariant<KotlinInt> = e
}

Bounds

// KOTLIN API CODE
class GenericClassBoundNumber<T: Number> (val value: T)
class GenericClassBoundComparable< T: Comparable<T>>(val value: T)

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("GenericClassBoundNumber")))
@interface SharedGenericClassBoundNumber<T> : SharedBase
- (instancetype)initWithValue:(T)value __attribute__((swift_name("init(value:)"))) __attribute__((objc_designated_initializer));
@property (readonly) T value __attribute__((swift_name("value")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("GenericClassBoundComparable")))
@interface SharedGenericClassBoundComparable<T> : SharedBase
- (instancetype)initWithValue:(T)value __attribute__((swift_name("init(value:)"))) __attribute__((objc_designated_initializer));
@property (readonly) T value __attribute__((swift_name("value")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class GenericClassBoundNumber<T> : KotlinBase where T : AnyObject {
    public init(value: T)
    open var value: T { get }
}

public class GenericClassBoundComparable<T> : KotlinBase where T : AnyObject {
    public init(value: T)
    open var value: T { get }
}

As we see from the code above, the bounds are ignored. That allows us to use the defined classes with Person, a type that either does not subclass Number or conforms to (implements) Comparable. As a result of that, we have a big potential for bugs as it is possible to use the generic class with types that it does not expect.

// SWIFT CLIENT CODE
func boundTest() {
    class Person {
        let firstName: String
        let lastName: String
        init(firstName fn: String, lastName ln: String) {
            firstName = fn
            lastName = ln
        }
    }
    let willSmith = Person(firstName: "Will", lastName: "Smith")
    
    let a = GenericClassBoundComparable<Person>(value: willSmith)
    let b = GenericClassBoundNumber<Person>(value: willSmith)
}

Interfaces

Kotlin Interfaces are mapped to Objective-C Protocols, which are not supported by Lightweight Generics. In fact, Swift Protocols do not rely on Type Parameters but on Associated Types.

Nullability

// KOTLIN API CODE
interface GenericInterface<T> { val value: T }
interface GenericInterfaceNonNullable<T: Any> { val value: T }

// EXPORTED OBJ-C HEADER
__attribute__((swift_name("GenericInterface")))
@protocol SharedGenericInterface
@required
@property (readonly) id _Nullable value __attribute__((swift_name("value")));
@end

__attribute__((swift_name("GenericInterfaceNonNullable")))
@protocol SharedGenericInterfaceNonNullable
@required
@property (readonly) id value __attribute__((swift_name("value")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public protocol GenericInterface {
    var value: Any? { get }
}

public protocol GenericInterfaceNonNullable {
    var value: Any { get }
}

Although the generic types are lost, binding to a non-nullable type will, like in the class case, translate to Any, a non-null type.

Variance and Bounds

// KOTLIN API CODE
interface GenericInterfaceCovariant<in T> { val value: Int }
interface GenericInterfaceContraVariant<out T> { val value: T }
interface GenericInterfaceBoundNumber<T: Number> { val value: T }
interface GenericInterfaceBoundComparable<T: Comparable<T>> { val value: T }

// EXPORTED OBJ-C HEADER
__attribute__((swift_name("GenericInterfaceCovariant")))
@protocol SharedGenericInterfaceCovariant
@required
@property (readonly) int32_t value_ __attribute__((swift_name("value_")));
@end

__attribute__((swift_name("GenericInterfaceContraVariant")))
@protocol SharedGenericInterfaceContraVariant
@required
@property (readonly) id _Nullable value __attribute__((swift_name("value")));
@end

__attribute__((swift_name("GenericInterfaceBoundNumber")))
@protocol SharedGenericInterfaceBoundNumber
@required
@property (readonly) id value __attribute__((swift_name("value")));
@end

__attribute__((swift_name("GenericInterfaceBoundComparable")))
@protocol SharedGenericInterfaceBoundComparable
@required
@property (readonly) id value __attribute__((swift_name("value")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public protocol GenericInterfaceCovariant {
    var value_: Int32 { get }
}

public protocol GenericInterfaceContraVariant {
    var value: Any? { get }
}

public protocol GenericInterfaceBoundNumber {
    var value: Any { get }
}

public protocol GenericInterfaceBoundComparable {
    var value: Any { get }
}

As said before, protocols do not support generics. That being so, any information about the type parameter is lost. Note the use of id in Objective-C which is bridged to Any. Both denote a reference to any type. As a result of that, while in Kotlin an instance of GenericInterface<String> can not be assigned to GenericInterface<Int>, because String and Int are incompatible types, it will be possible in Swift because they will both be seen as an instance of Any.

Note that even if you bound the type parameter, the type in Swift will still be Any, and not the bound type as it would normally happen after type erasure.

Functions and Methods

Both are not supported by Lightweight Generics, but there’s a few interesting things to note:

• Again, biding to a non-nullable type will ensure the type is not null in Objective-C and Swift.
• Non-bound type arguments are mapped to Any. Because of that, there is no way to enforce type constraints. For instance, in someFunctionTwoTypeArguments, both valueOfTypeT and anotherValueOfTypeT are bound to type argument T. But in Swift, it will be possible to use different types for them.
• When the type argument is bound to an exported type, Kotlin native compiler will fortunately do type erasure, which will bring some type safety.

// KOTLIN API CODE
interface MyInterface
open class MyClass
open class Container<out T>(val value: T)

class FunctionGenerics {
    fun <T> someFunction(value: T): T = value
    fun <T> someFunctionNonNull(value: T): T where T: Any = value
    fun <T> someFunctionReturnsClass(value: T): Container<T> = Container(value)
    fun <T> someFunctionReturnsInterface(): Sequence<T> = sequenceOf()
    fun <T, U> someFunctionTwoTypeArguments(valueOfTypeT: T, anotherValueOfTypeT: T, valueOfTypeU: U) = Unit
    fun <T : MyInterface> someFunctionBoundByInterface(a: T): T = a
    fun <T : MyClass> someFunctionBoundByClass(a: T): T = a
    fun <T : Comparable<T>> someFunctionBoundByGenericInterface(a: T, b: T): Int = a.compareTo(b)
    fun <T : Container<T>> someFunctionBoundByGenericClass(a: T): T = a
}

// EXPORTED OBJ-C HEADER
__attribute__((swift_name("MyInterface")))
@protocol SharedMyInterface
@required
@end

__attribute__((swift_name("MyClass")))
@interface SharedMyClass : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
@end

__attribute__((swift_name("Container")))
@interface SharedContainer<__covariant T> : SharedBase
- (instancetype)initWithValue:(T _Nullable)value __attribute__((swift_name("init(value:)"))) __attribute__((objc_designated_initializer));
@property (readonly) T _Nullable value __attribute__((swift_name("value")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("FunctionGenerics")))
@interface SharedFunctionGenerics : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
- (id _Nullable)someFunctionValue:(id _Nullable)value __attribute__((swift_name("someFunction(value:)")));
- (SharedMyClass *)someFunctionBoundByClassA:(SharedMyClass *)a __attribute__((swift_name("someFunctionBoundByClass(a:)")));
- (SharedContainer *)someFunctionBoundByGenericClassA:(SharedContainer *)a __attribute__((swift_name("someFunctionBoundByGenericClass(a:)")));
- (int32_t)someFunctionBoundByGenericInterfaceA:(id)a b:(id)b __attribute__((swift_name("someFunctionBoundByGenericInterface(a:b:)")));
- (id<SharedMyInterface>)someFunctionBoundByInterfaceA:(id<SharedMyInterface>)a __attribute__((swift_name("someFunctionBoundByInterface(a:)")));
- (id)someFunctionNonNullValue:(id)value __attribute__((swift_name("someFunctionNonNull(value:)")));
- (SharedContainer<id> *)someFunctionReturnsClassValue:(id _Nullable)value __attribute__((swift_name("someFunctionReturnsClass(value:)")));
- (id<SharedKotlinSequence>)someFunctionReturnsInterface __attribute__((swift_name("someFunctionReturnsInterface()")));
- (void)someFunctionTwoTypeArgumentsValueOfTypeT:(id _Nullable)valueOfTypeT anotherValueOfTypeT:(id _Nullable)anotherValueOfTypeT valueOfTypeU:(id _Nullable)valueOfTypeU __attribute__((swift_name("someFunctionTwoTypeArguments(valueOfTypeT:anotherValueOfTypeT:valueOfTypeU:)")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public protocol MyInterface {
}

open class MyClass : KotlinBase {
    public init()
}

open class Container<T> : KotlinBase where T : AnyObject {
    public init(value: T?)
    open var value: T? { get }
}

public class FunctionGenerics : KotlinBase {
    public init()
    
    open func someFunction(value: Any?) -> Any?
    open func someFunctionNonNull(value: Any) -> Any
    open func someFunctionReturnsClass(value: Any?) -> Container<AnyObject>
    open func someFunctionReturnsInterface() -> KotlinSequence
    open func someFunctionTwoTypeArguments(valueOfTypeT: Any?, anotherValueOfTypeT: Any?, valueOfTypeU: Any?)
    open func someFunctionBoundByInterface(a: MyInterface) -> MyInterface
    open func someFunctionBoundByClass(a: MyClass) -> MyClass
    open func someFunctionBoundByGenericInterface(a: Any, b: Any) -> Int32
    open func someFunctionBoundByGenericClass(a: Container<AnyObject>) -> Container<AnyObject>
}

This time we saw how Generics are supported by Kotlin Multiplatform. In the next and final chapter, we will combine the lessons learned in this article and the previous one to tackle Flows.

Writing Swift-friendly Kotlin Multiplatform APIs

References

• GALLIGAN, Kevin — Kotlin Native Interop Generics https://medium.com/@kpgalligan/kotlin-native-interop-generics-15eda6f6050f
• BRYS, Salomon — Kotlin/Multiplatform for iOS developers: state & future https://www.youtube.com/watch?v=j-zEAMcMcjA
• Swift and Objective-C Interoperability — https://developer.apple.com/videos/play/wwdc2015/401/
• Using Imported Lightweight Generics in Swift — https://developer.apple.com/documentation/swift/using-imported-lightweight-generics-in-swift
• Importing Objective-C Lightweight Generics — https://github.com/apple/swift-evolution/blob/main/proposals/0057-importing-objc-generics.md
• Objective-C lightweight generics — https://lists.gnu.org/archive/html/gnustep-dev/2015-07/msg00006.html
• iOS Tech Set — Generics in Objective-C https://medium.com/ios-os-x-development/generics-in-objective-c-8f54c9cfbce7

Writing Swift-friendly Kotlin Multiplatform APIs — Part VIII: Generics was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learning how to create a simple version of Retrofit from scratch

Retrofit is undoubtedly one of the most important libraries for Android development. It allows implementing REST APIs by just specifying an interface, without having to deal with all the details of OkHttp. It is pretty flexible: you can choose any sort of marshaling library, and you can pick among callbacks, RxJava, or even coroutines. But have you wondered how all that magic happens? The solution to that puzzle is Proxy. Not a network proxy or a proxy like the design pattern defined by GoF. I am talking about the Java class Proxy from the reflect package.

This article is part of a series. To see the other articles click here.

Proxy

The Proxy class allows you to dynamically implement interfaces by intercepting calls to methods. All you need to do is to implement an InvocationHandler, some sort of listener that tells you which method was called and its parameters.

Let’s start with an elementary interface:

data class Person(val name: String, val surname: String)
interface MyInterface {
    fun methodOne(param1: String, param2: Int)
    fun methodTwo(param: Person): String
}

To implement MyInterface dynamically, we just need a few lines of code:

fun main() {
    val dynamicObject = Proxy.newProxyInstance(
        MyInterface::class.java.classLoader,
        arrayOf(MyInterface::class.java)
    ) { proxy, method, args ->
        println("Called ${method.toGenericString()} with params: ${Arrays.toString(args)}")
        // Returning null so we don't have to deal with the return type for now
        null
    } as MyInterface

    dynamicObject.methodOne("Hello", 42)
    dynamicObject.methodTwo(Person("Julius", "Caesar"))
}

And those lines of code will print:

Called public abstract void MyInterface.methodOne(java.lang.String,int) with params: [Hello, 42]
Called public abstract java.lang.String MyInterface.methodTwo(Person) with params: [Person(name=Julius, surname=Caesar)]

Important: Proxy can only be used with interfaces. If you use it with a class it will crash:

Exception in thread "main" java.lang.IllegalArgumentException: MyClass is not an interface
 at java.base/java.lang.reflect.Proxy$ProxyBuilder.validateProxyInterfaces(Proxy.java:706)
 at java.base/java.lang.reflect.Proxy$ProxyBuilder.<init>(Proxy.java:648)
 at java.base/java.lang.reflect.Proxy$ProxyBuilder.<init>(Proxy.java:656)
 at java.base/java.lang.reflect.Proxy.lambda$getProxyConstructor$0(Proxy.java:429)
 at java.base/jdk.internal.loader.AbstractClassLoaderValue$Memoizer.get(AbstractClassLoaderValue.java:329)
 at java.base/jdk.internal.loader.AbstractClassLoaderValue.computeIfAbsent(AbstractClassLoaderValue.java:205)
 at java.base/java.lang.reflect.Proxy.getProxyConstructor(Proxy.java:427)
 at java.base/java.lang.reflect.Proxy.newProxyInstance(Proxy.java:1037)
 at MainKt.main(Main.kt:30)
 at MainKt.main(Main.kt)

We will learn how to overcome that limitation in the next chapter when I will tell you how mock libraries like Mockito and Mockk work.

Implementing Retrofit

Now that we know the basics, we shall be able to implement a simplified version of Retrofit. Our version will only support HTTP GET requests and query parameters. Thus, our first step is to define a couple of annotations to define the request’s URL and query parameters:

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class GET(val baseUrl: String)

@Target(AnnotationTarget.VALUE_PARAMETER)
@Retention(AnnotationRetention.RUNTIME)
annotation class Query(val parameterName: String)

To keep this implementation short, our version of Call will only allow synchronous requests:

interface Call<out T> {
    fun execute(): T
}

We now need to extract the values of the annotations of the methods of the interface in order to create an OkHttp Request:

private fun createRequest(method: Method, args: Array<Any?>): Request {
    val baseUrl = method.getAnnotation(GET::class.java).baseUrl
    val paramNames = method.parameterAnnotations.flatten().map { (it as Query).parameterName }
    val url = HttpUrl.parse(baseUrl).newBuilder().apply {
        paramNames.forEachIndexed { index, paramName -> addQueryParameter(paramName, args[index].toString()) }
    }.build()
    return Request.Builder()./service/https://medium.com/url(url).build()
}

We also need to extract the actual response type from the method thru reflection:

private fun extractResponseType(method: Method): Class<*> {
    return (method.genericReturnType as ParameterizedType).actualTypeArguments[0] as Class<*>
}

Now that we created the request and we know the response type, we can create the network call and parse the response:

private fun <T> createCall(request: Request, responseClass: Class<T>): Call<T> {
    return object : Call<T> {
        override fun execute(): T  {
            val response = httpClient.newCall(request)
                              .execute().body().string()
            return objectMapper.readValue(response, responseClass)
        }
    }
}

Now that we have all the basic blocks, we can dynamically implement the interface :

fun <T> createService(serviceClass: Class<T>): T {
    return Proxy.newProxyInstance(serviceClass.classLoader, arrayOf(serviceClass)) {
        thiz: Any, method: Method, args: Array<Any?> ->
            val request = createRequest(method, args)
            val responseType = extractResponseType(method)
            createCall(request, responseType)
    } as T
}

With our simplified implementation of Retrofit done, we can now try it with the OpenWeather API :

data class Weather(val main: Main)
data class Main(val temp: Double)
data class UvIndex(val value: Double)

interface OpenWeatherMapApi {
    @GET("http://samples.openweathermap.org/data/2.5/weather")
    fun getWeather(@Query("q") city: String, @Query("appid") apiKey: String): Call<Weather>

    @GET("http://samples.openweathermap.org/data/2.5/uvi")
    fun getUvIndex(@Query("lat") lat: Double, @Query("lon") lon: Double, @Query("appid") apiKey: String): Call<UvIndex>
}

fun main(args: Array<String>) {
    val API_KEY = "YOUK KEY"
    val service = SimpleRetrofit().createService(OpenWeatherMapApi::class.java)
    val weather = service.getWeather("London", API_KEY).execute()
    val uvIndex = service.getUvIndex(37.75, -122.37, API_KEY).execute()
    println(weather)
    println(uvIndex)
}

The full implementation

And here is how all the pieces we built above were put together:

This time was Retrofit. The last time was ButterKnife by Jake Wharton. Next time we will overcome the restriction imposed by Proxy, and create a simple version of a Mock Library like Mockito or Mockk. For now, you can see all the articles here:

Let Kotlin do the code for you

References

• Java™ Platform Standard Ed. 8 — Proxy https://docs.oracle.com/javase/8/docs/api/java/lang/reflect/Proxy.html
• Java™ Platform Standard Ed. 8 — InvocationHandler https://docs.oracle.com/javase/8/docs/api/java/lang/reflect/InvocationHandler.html

Let Kotlin do the code for you — Part II: Retrofit and Proxy was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to code libraries that your iOS teammates will not frown upon using them. In this chapter: Coroutines

In the beginning, the team led by Andy Rubin started with Java threads, Services, and Looper. But one had to write a lot of boilerplate code. Then we were advised to move to AsyncTask, but rotating the device would make that thing crash. But then they created a non-intuitive version of that: Loaders. When Jake Wharton began to play with RxJava, everyone followed suit. Then Jetbrains dug up a concept from 1959, and now we have Coroutines in Kotlin. That is the short history of concurrent programming in Android.

This article is part of a series, see the other articles here

Coroutines

Let us start with a simple example of two suspend functions. The idea is to use the result of fetchString as a parameter for calculateHash.

// KOTLIN API CODE
@OptIn(ExperimentalObjCName::class)
suspend fun fetchString(@ObjCName(swiftName = "_") param: Int): String {
    println("Starting")
    delay(100)
    withContext(Dispatchers.IO) {
        println("in some IO thread")
        delay(1000)
    }
    println("back on original thread")
    return param.toString()
}

@OptIn(ExperimentalObjCName::class)
suspend fun calculateHash(@ObjCName(swiftName = "_") param: String) = param.hashCode()

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ExampleKt")))
@interface SharedExampleKt : SharedBase
/**
 * @note This method converts instances of CancellationException to errors.
 * Other uncaught Kotlin exceptions are fatal.
*/
+ (void)fetchStringParam:(int32_t)param completionHandler:(void (^)(NSString * _Nullable, NSError * _Nullable))completionHandler __attribute__((swift_name("fetchString(_:completionHandler:)")));  
/**
 * @note This method converts instances of CancellationException to errors.
 * Other uncaught Kotlin exceptions are fatal.
*/
+ (void)calculateHashParam:(NSString *)param completionHandler:(void (^)(SharedInt * _Nullable, NSError * _Nullable))completionHandler __attribute__((swift_name("calculateHash(_:completionHandler:)")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class ExampleKt : KotlinBase {    
    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    open class func fetchString(_ param: Int32, completionHandler: @escaping (String?, Error?) -> Void)

    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    open class func fetchString(_ param: Int32) async throws -> String

    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    open class func calculateHash(_ param: String, completionHandler: @escaping (KotlinInt?, Error?) -> Void)

    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    open class func calculateHash(_ param: String) async throws -> KotlinInt
}

Surprisingly in Swift our suspend functions came in two flavors:

• The Objective-C-matching completion handler flavor;
• The asynchronous function flavor, which was introduced in Swift 5.5.

Completion Handler

// SWIFT CLIENT CODE
func usingCompletionHandler() {
    ExampleKt.fetchString(1) {
        stringResult, error  in
        if let error = error {
            print("We had an error: \(error)")
        } else {
            ExampleKt.calculateHash(stringResult ?? "") {
               intResult, error in
                if let error = error {
                    print("We had an error: \(error)")
                } else {
                    print("Final result \(intResult ?? 0)")
                }
            }
        }
    }
}

You may realized by now that completion handler is just Apple’s fancy name for callbacks. The disadvantages of using callbacks are clear:

• It can easily create a Pyramid of doom or callback hell;
• The coroutines cannot be canceled.

Tasks and async/await

// SWIFT CLIENT CODE
func usingTask() {
    let task = Task { @MainActor in
        do {
            let stringResult = try await ExampleKt.fetchString(1)
            let intResult = try await ExampleKt.calculateHash(stringResult)
            print("Final result \(intResult)")
        } catch {
            print("We had an error: \(error)")
        }
    }
    // This doesn't do what you think it'd do
    task.cancel()
}

This looks cleaner, closer to how we would do in Kotlin. However task.cancel() does not work. The coroutine keeps running. The reason for that is straightforward. Note that the async functions only appear on the Objective-C translation to Swift. As we saw in Part V of this series, Swift bridging for Objective-C can substantially change the method’s signature, and that is also the case here. From Swift 5.5 and on, methods with completion handlers are translated to asynchronous functions. Because that process happens entirely on the Swift side, the task is completely unaware of the underlying coroutine, and therefore it cannot pass the cancellation request down to Kotlin.

Cancellation, dispatchers, coroutine context, task locals etc. are not propagated between Kotlin and Swift, they are discarded at the boundary between Kotlin and Swift.

You might be curious about that @MainActor annotation. Shall we remove it and see what happens?

2023-08-04 21:34:05.764759-0700 iosApp[3356:2506280] *** Terminating app due to uncaught exception 'NSGenericException', reason: 'Calling Kotlin suspend functions from Swift/Objective-C is currently supported only on main thread'
*** First throw call stack:
(
 0   CoreFoundation                      0x00007ff8004288ab __exceptionPreprocess + 242
 1   libobjc.A.dylib                     0x00007ff80004dba3 objc_exception_throw + 48
 2   CoreFoundation                      0x00007ff800428789 -[NSException initWithCoder:] + 0
 3   shared                              0x00000001025c7c40 Kotlin_ObjCExport_createContinuationArgument + 80
 4   shared                              0x00000001023eb1c9 objc2kotlin_kfun:io.aoriani.kmpapp#networkCall#suspend(kotlin.Int;kotlin.coroutines.Continuation<kotlin.String>){}kotlin.Any + 185
 5   iosApp                              0x00000001017dba60 $s6iosApp9usingTaskyyFyyYaYbcfU_TY0_ + 208
 6   iosApp                              0x00000001017ddf01 $sxIeghHr_xs5Error_pIegHrzo_s8SendableRzs5NeverORs_r0_lTRTQ0_ + 1
 7   iosApp                              0x00000001017de211 $sxIeghHr_xs5Error_pIegHrzo_s8SendableRzs5NeverORs_r0_lTRTATQ0_ + 1
 8   libswift_Concurrency.dylib          0x00007ff835f7cfc1 _ZL23completeTaskWithClosurePN5swift12AsyncContextEPNS_10SwiftErrorE + 1
)
libc++abi: terminating with uncaught exception of type NSException
terminating with uncaught exception of type NSException
CoreSimulator 857.14 - Device: iPhone 14 Pro (CA3A7FC8-1DD6-4E44-BCE1-5A6D92CB1F3D) - Runtime: iOS 16.2 (20C52) - DeviceType: iPhone 14 Pro
*** Terminating app due to uncaught exception 'NSGenericException', reason: 'Calling Kotlin suspend functions from Swift/Objective-C is currently supported only on main thread'

The app crashes because suspend functions can only be started from iOS’ main thread and @MainActor tells Swift to run the task on the main dispatch queue. The reasons for that are stated in KT-51297:

Initially, calling Kotlin suspend functions on non-main thread from Swift was prohibited because it would be incompatible with particular approaches required by the old memory manager. Specifically, because of this kind of code: https://github.com/Kotlin/kotlinx.coroutines/blob/952ee683ee487438b5d01ab03b4780a4ab351719/kotlinx-coroutines-core/native/src/internal/Sharing.kt#L188
It dispatches a continuation to be resumed on the original thread.

The problem is: if the original thread doesn’t have a supported event loop, the task will never run, and the coroutine will never be resumed.

Additionally, IIRC, Apple doesn’t provide a way to dispatch a task to a particular (GCD-managed) background thread. So GCD-managed background threads just can’t have a “supported event loop” mentioned above.

As a consequence, if native-mt coroutines are used and Kotlin suspend function is called from Swift on a “regular” background thread, the coroutine that is started by this call will never resume after a suspension.
To avoid this, we prohibited calling Kotlin suspend function in Swift from non-main threads.

From Kotlin 1.7.20 and on you can remove the check for the main thread by adding the following to your gradle.properties file:

kotlin.native.binary.objcExportSuspendFunctionLaunchThreadRestriction=none

Just make sure you do not use the native-mt version of kotlinx-coroutines if you enable this.

A solution

Let me take a stab at the problem. As we saw in Part IV, we will have to write some Swift code to fill the gaps left by Objective-C. But for now, let’s concentrate on the Kotlin side. We need to wrap the suspend function with a type that provides a handle that allows us to:

• Launch the suspend function on a predefined CoroutineScope;
• Cancel the coroutine’s job.

That is what bellow SuspendWrapper is for. By the way, @HiddenFromObjC prevents the symbol from being exported to Objective-C. Note that I used @ObjCName to effectively replace the original suspend functions by their wrapped versions.

// KOTLIN API CODE
@OptIn(ExperimentalObjCRefinement::class)
@HiddenFromObjC
suspend fun fetchString(param: Int): String {
    return try {
        println("Starting")
        delay(100)
        withContext(Dispatchers.IO) {
            println("in some IO thread")
            delay(1000)
        }
        println("Back on original thread")
        param.toString()
    } catch (cancellation: CancellationException) {
        println("I was cancelled")
        throw cancellation
    }
}

@OptIn(ExperimentalObjCRefinement::class)
@HiddenFromObjC
suspend fun calculateHash(param: String) = param.hashCode()

class SuspendWrapper<out T> internal constructor(
    private val scope: CoroutineScope,
    private val block: suspend () -> T & Any
) {
    private var job: Job? = null
    private var isCancelled = false

    fun cancel() {
        isCancelled = true
        job?.cancel()
    }

    suspend fun run(): T & Any {
        val deferred = scope.async(start = CoroutineStart.LAZY) { block() }
        job = deferred
        if (isCancelled) deferred.cancel() else deferred.start()
        return deferred.await()
    }
}

internal fun <T : Any> (suspend () -> T).wrap(scope: CoroutineScope = MainScope()): SuspendWrapper<T> {
    return SuspendWrapper(scope = scope, block = this)
}

private val mainScope = MainScope()

@ObjCName("fetchString")
fun wrappedFetchString(param: Int) = suspend { fetchString(param) }.wrap(mainScope)

@ObjCName("calculateHash")
fun wrappedCalculateHash(param: String) = suspend { calculateHash(param) }.wrap(mainScope)

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("SuspendWrapper")))
@interface SharedSuspendWrapper<__covariant T> : SharedBase
- (void)cancel __attribute__((swift_name("cancel()")));

/**
 * @note This method converts instances of CancellationException to errors.
 * Other uncaught Kotlin exceptions are fatal.
*/
- (void)runWithCompletionHandler:(void (^)(T _Nullable, NSError * _Nullable))completionHandler __attribute__((swift_name("run(completionHandler:)")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ExampleKt")))
@interface SharedExampleKt : SharedBase
+ (SharedSuspendWrapper<SharedInt *> *)calculateHashParam:(NSString *)param __attribute__((swift_name("calculateHash(param:)")));
+ (SharedSuspendWrapper<NSString *> *)fetchStringParam:(int32_t)param __attribute__((swift_name("fetchString(param:)")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class SuspendWrapper<T> : KotlinBase where T : AnyObject {
    open func cancel()

    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    open func run(completionHandler: @escaping (T?, Error?) -> Void)

    /**
     * @note This method converts instances of CancellationException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    open func run() async throws -> T
}

public class ExampleKt : KotlinBase {
    open class func calculateHash(param: String) -> SuspendWrapper<KotlinInt>
    open class func fetchString(param: Int32) -> SuspendWrapper<NSString>
}

On the Swift side, we need to be able to launch the task and be notified when the task is canceled. Asking my iOS teammates, Marquis Kurt pointed me to this nice function:

withTaskCancellationHandler(operation:onCancel:) | Apple Developer Documentation

Given that, I just need to write a function that connects my Kotlin wrapper to that Swift function, and voilà.

// SWIFT CLIENT CODE
func suspend<T>(_ wrapper: SuspendWrapper<T>) async throws -> T {
    return try await withTaskCancellationHandler {
        @MainActor in try await wrapper.run()
    } onCancel: {
        wrapper.cancel()
    }
}

func usingTask() {
    let task = Task {
        do {
            let stringResult = try await suspend(ExampleKt.fetchString(param: 1))
            let intResult = try await suspend(ExampleKt.calculateHash(param: stringResult as String))
            print("Final result \(intResult)")
        } catch {
            print("We had an error: \(error)")
        }
    }
    //It works now !
    task.cancel()
}

Now canceling the task will also cancel the coroutine!

KMP-NativeCoroutines

Of course, I am not the only one to have this problem. Several libraries were created to address suspend functions:

• Koru by FutureMind — You can see how to use it in this talk given by Labellarte and Rotolo at Fosdem 2023, but it doesn’t seem to have been updated after Kotlin 1.8.0;
• SKIE by Touchlab — It requires an API key. I requested a trial one, but no answer from Touchlab so far;
• KMP-NativeCoroutines by Rick Clefas — It is simple to use and it is so being actively developed that when I reported an issue, Rick fixed it in a matter of couple days and pushed a new release. A deep dive into this library was made by John O’Reilly, but let us see how it could be applied to our code.

// KOTLIN API CODE
@NativeCoroutineScope
internal val myCoroutineScope = MainScope()

@NativeCoroutines
suspend fun fetchString(param: Int): String {
    println("Starting")
    delay(100)
    withContext(Dispatchers.IO) {
        println("in some IO thread")
        delay(1000)
    }
    println("back on original thread")
    return param.toString()
}

@NativeCoroutines
suspend fun calculateHash(param: String) = param.hashCode()

The @NativeCouroutineScope annotation defines which scope to use. The @NativeCoroutines one does two things. First, it prevents the annotated functions from being exported to Objective-C. Second, after the annotation processing phase, it generates code for all iOS variants:

// ios* CODE GENERATED BY KSP

@ObjCName(name = "fetchString")
public fun fetchStringNative(`param`: Int): NativeSuspend<String> = nativeSuspend(myCoroutineScope)
    { fetchString(`param`) }

@ObjCName(name = "calculateHash")
public fun calculateHashNative(`param`: String): NativeSuspend<Int> =
    nativeSuspend(myCoroutineScope) { calculateHash(`param`) }

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ExampleNativeKt")))
@interface SharedExampleNativeKt : SharedBase
+ (SharedKotlinUnit *(^(^)(SharedKotlinUnit *(^)(SharedInt *, SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError *, SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError *, SharedKotlinUnit *)))(void))calculateHashParam:(NSString *)param __attribute__((swift_name("calculateHash(param:)")));
+ (SharedKotlinUnit *(^(^)(SharedKotlinUnit *(^)(NSString *, SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError *, SharedKotlinUnit *), SharedKotlinUnit *(^)(NSError *, SharedKotlinUnit *)))(void))fetchStringParam:(int32_t)param __attribute__((swift_name("fetchString(param:)")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class ExampleNativeKt : KotlinBase {
    open class func calculateHash(param: String) -> (@escaping (KotlinInt, KotlinUnit) -> KotlinUnit, @escaping (Error, KotlinUnit) -> KotlinUnit, @escaping (Error, KotlinUnit) -> KotlinUnit) -> () -> KotlinUnit
    open class func fetchString(param: Int32) -> (@escaping (String, KotlinUnit) -> KotlinUnit, @escaping (Error, KotlinUnit) -> KotlinUnit, @escaping (Error, KotlinUnit) -> KotlinUnit) -> () -> KotlinUnit
}

Now on the Swift side, we use asyncFunction to launch the coroutine:

// SWIFT CLIENT CODE
func usingTask() {
    let task = Task {
        do {
            let stringResult = try await asyncFunction(for: ExampleNativeKt.fetchString(param: 1))
            let intResult = try await asyncFunction(for: ExampleNativeKt.calculateHash(param: stringResult))
            print("Final result \(intResult)")
        } catch {
            print("We had an error: \(error)")
        }
    }
    ...
    task.cancel()
}

This week we covered Coroutines. Next week, we will deal with Flows. Do not miss it! Meanwhile, take the time to read the other articles of the series:

Writing Swift-friendly Kotlin Multiplatform APIs

References

• Native: allow calling Kotlin suspend functions on non-main thread from Swift — https://youtrack.jetbrains.com/issue/KT-51297/Native-allow-calling-Kotlin-suspend-functions-on-non-main-thread-from-Swift
• KMM New Memory Model Suspend Fun Main thread — https://youtrack.jetbrains.com/issue/KT-51166/KMM-New-Memory-Model-Suspend-Fun-Main-thread
• Kotlin docs — iOS Integration-Calling Kotlin suspending functions https://kotlinlang.org/docs/native-ios-integration.html#calling-kotlin-suspending-functions
• KLIMCZAK, Michał (Michał Klimczak) — Handling Kotlin Multiplatform Coroutines in Swift — Koru https://www.futuremind.com/insights/handling-kotlin-multiplatform-coroutines-koru
• ROTOLO, Paolo (Paolo Rotolo) and LABELLARTE, Anna — Kotlin Multiplatform for Android & iOS library developers: Tips for writing Kotlin Multiplatform Android/iOS libraries https://fosdem.org/2023/schedule/event/kmp_for_android_and_ios_library_developers/
• Calling Objective-C APIs Asynchronously https://developer.apple.com/documentation/swift/calling-objective-c-apis-asynchronously
• O’REILLY, John — Bridging the gap between Swift 5.5 concurrency and Kotlin Coroutines with KMP-NativeCoroutines https://johnoreilly.dev/posts/kmp-native-coroutines/

Writing Swift-friendly Kotlin Multiplatform APIs — Part VII: Coroutines was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to code libraries that your iOS teammates will not frown upon using them. In this chapter: enums and sealed classes.

I love Swift enums, even though I am a Kotlin developer. And iOS devs certainly do too. Let me show you why with one example:

// SWIFT CLIENT CODE
enum NetworkResult {
    case success(data: Data)
    case failure(code: Int, error: Error)
    case notConnected
}

func networkCall() -> NetworkResult {
    ....
}

func retrieveSomething() {
    let result = networkCall()
    switch result {
    case let .success(data):
        print(data)
    case let .failure(code, error) where (400..<500).contains(code):
        print("Client error: \(error)")
    case let .failure(_, error):
        print("Server error: \(error)")
    case .notConnected:
        print("Not connected")
    }
}

This article is part of a series, see the other articles here

Like any other regular enum type, the Swift enum allows you to define a finite set of values. But unlike the Kotlin one, those values are not immutable. Swift enums can have associated values, i.e., they can carry data that is defined at instantiation time. See the example above. Not only the enum can represent all the possible types of response that we can get from a network call, but if the type is “success” it will contain the response data. Similarly, if the type is “error” it will contain the error code, and so on. Also, note how switch (the Swift equivalent to Kotlin when) works nicely with enums in a pattern-match style. If we really want to entice Swift developers to use our Kotlin Multiplatform APIs we need to create code that can be used as conveniently and efficiently as Swift enums. Are we able to do so? I know what you are thinking but hold that thought for a moment.

Kotlin Enums

Our obvious first candidate is the Kotlin enum. Let us see how they are exported:

// KOTLIN API CODE
enum class MatterState(val temp: Int) {
    SOLID(0),
    LIQUID(25),
    GAS(100),
    PLASMA(10_000)
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("MatterState")))
@interface SharedMatterState : SharedKotlinEnum<SharedMatterState *>
+ (instancetype)alloc __attribute__((unavailable));
+ (instancetype)allocWithZone:(struct _NSZone *)zone __attribute__((unavailable));
- (instancetype)initWithName:(NSString *)name ordinal:(int32_t)ordinal __attribute__((swift_name("init(name:ordinal:)"))) __attribute__((objc_designated_initializer)) __attribute__((unavailable));
@property (class, readonly) SharedMatterState *solid __attribute__((swift_name("solid")));
@property (class, readonly) SharedMatterState *liquid __attribute__((swift_name("liquid")));
@property (class, readonly) SharedMatterState *gas __attribute__((swift_name("gas")));
@property (class, readonly) SharedMatterState *plasma __attribute__((swift_name("plasma")));
+ (SharedKotlinArray<SharedMatterState *> *)values __attribute__((swift_name("values()")));
@property (readonly) int32_t temp __attribute__((swift_name("temp")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class MatterState : KotlinEnum<MatterState> {
    open class var solid: MatterState { get }
    open class var liquid: MatterState { get }
    open class var gas: MatterState { get }
    open class var plasma: MatterState { get }
    open class func values() -> KotlinArray<MatterState>
    open var temp: Int32 { get }
}

// SWIFT CLIENT CODE
let state: MatterState = .gas
switch state {
case .gas: print("gas")
case .liquid: print("liquid")
case .solid: print("solid at \(state.temp)")
case .plasma: print("plasma")
default:
     break
}

The problem

Objective-C has only C-Style enums. In C the values can only be associated with a unique integer. Therefore, a Kotlin enum cannot be perfectly translated to Objective-C. If you are not familiar with either Objective-C or Swift, here is a rough translation of how the Kotlin enum is perceived by them:

class MatterState(val temp: Int): Enum<MatterState> {
    companion object {
        @JvmField val solid: MatterState = MatterState(0)
        @JvmField val liquid: MatterState = MatterState(25)
        @JvmField val gas: MatterState = MatterState(100)
        @JvmField val plasma: MatterState = MatterState(10_000)

        @JvmStatic
        fun values(): Array<MatterState> = arrayOf(solid, liquid, gas, plasma)
    }
}

Thus in Swift, each one of values of the enum becomes a static immutable instance of that enum type. As we saw in the example above, that enables a pretty similar syntax to Swift enums. However, Swift has no way of knowing that those are the only possible values. Consequently, the switch will require a default case, because, like its Kotlin counterpart when, it must be exhaustive, even though the default case will never be hit.

Sealed Classes

I bet that sealed classes were your first thought after I introduced Swift enums to you. Let us see how well they can do :

// KOTLIN API CODE
sealed class ReturnValue {
    object Loading : ReturnValue()
    class Success(val data: String) : ReturnValue()
    class Error(val errorCode: Int) : ReturnValue()
}

// EXPORTED OBJ-C HEADER
__attribute__((swift_name("ReturnValue")))
@interface SharedReturnValue : SharedBase
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ReturnValue.Error")))
@interface SharedReturnValueError : SharedReturnValue
- (instancetype)initWithErrorCode:(int32_t)errorCode __attribute__((swift_name("init(errorCode:)"))) __attribute__((objc_designated_initializer));
@property (readonly) int32_t errorCode __attribute__((swift_name("errorCode")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ReturnValue.Loading")))
@interface SharedReturnValueLoading : SharedReturnValue
+ (instancetype)alloc __attribute__((unavailable));
+ (instancetype)allocWithZone:(struct _NSZone *)zone __attribute__((unavailable));
+ (instancetype)loading __attribute__((swift_name("init()")));
@property (class, readonly, getter=shared) SharedReturnValueLoading *shared __attribute__((swift_name("shared")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ReturnValue.Success")))
@interface SharedReturnValueSuccess : SharedReturnValue
- (instancetype)initWithData:(NSString *)data __attribute__((swift_name("init(data:)"))) __attribute__((objc_designated_initializer));
@property (readonly) NSString *data __attribute__((swift_name("data")));
@end

// HEADER "TRANSLATED" TO SWIFT 
open class ReturnValue : KotlinBase {}
extension ReturnValue {
    public class Loading : ReturnValue {        
        public convenience init()
        open class var shared: ReturnValue.Loading { get }
    }

    public class Error : ReturnValue {
        public init(errorCode: Int32)
        open var errorCode: Int32 { get }
    }
    
    public class Success : ReturnValue {
        public init(data: String)
        open var data: String { get }
    }
}

// SWIFT CLIENT CODE
let result: ReturnValue = ReturnValue.Loading.shared
switch result {
case is ReturnValue.Loading: print("loading")
case let success as ReturnValue.Success:
    print("success \(success.data)")
case let error as ReturnValue.Error:
    print("error \(error.errorCode)")
default:
    break
}

The problem

Objective-C and Swift will see your sealed classes as a simple and plain class hierarchy, in view of the fact that the concept of sealed classes does not exist for them. Writing a switch statement becomes a cumbersome task because all you can do is attempt to downcast to the correct subclass. And again, a useless default case will be needed to satisfy the exhaustive requirement.

The solution

As we saw in Part IV, we may have to resort to Swift wrappers in order to improve the API. Thus we define a matching Swift enum, and provide a nullable constructor extension (yes, that is possible in Swift!) to wrap our Kotlin sealed class:

// SWIFT CLIENT CODE
enum ReturnValueSwift {
    case loading
    case success(data: String)
    case error(errorCode: Int)
}

extension ReturnValueSwift {
    init?(_ value: ReturnValue) {
        switch value {
        case is ReturnValue.Loading:
            self = .loading
        case let success as ReturnValue.Success:
            self = .success(data: success.data)
        case let error as ReturnValue.Error:
            self = .error(errorCode: Int(error.errorCode))
        default:
            return nil
        }
    }
}

func returnValueTest() {
    if let result = ReturnValueSwift(ReturnValue.Loading.shared) {
        switch result {
        case .loading:
            print("loading")
        case let .success(data):
            print("success \(data)")
        case let .error(errorCode):
            print("error \(errorCode)")
            
        }
    }
}

Writing wrappers for every enum and sealed class hierarchy will be a tedious process, especially if you are not fluent in Swift. Fortunately, some folks already wrote compiler plugins that can automate the process for you:

• MOKO KSwift
• Touchlabs SKIE

In this installment, we learned how Kotlin enum and sealed classes are translated to Swift. We also saw how we can use Swift extensions again to improve the exported APIs. See you again next week when I am gonna cover coroutines and flows. Meanwhile, do not forget to check the other episodes of this series :

Writing Swift-friendly Kotlin Multiplatform APIs

References

• The Swift Programming Language (5.9 beta) — Enumerations — Associated Values — https://docs.swift.org/swift-book/documentation/the-swift-programming-language/enumerations/#Associated-Values
• Swift Tip: Enum Initializers — https://www.objc.io/blog/2018/03/13/mutable-self/
• MIKHAILOV, Aleksey — How to implement Swift-friendly API with Kotlin Multiplatform Mobile — https://medium.com/icerock/how-to-implement-swift-friendly-api-with-kotlin-multiplatform-mobile-e68521a63b6d

Writing Swift-friendly Kotlin Multiplatform APIs — Part VI was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to code libraries that your iOS teammates will not frown upon using them. In this chapter: Exceptions!

The machine has just dispensed your expresso. You grab your cup, and, suddenly you notice a Macbook Pro with a Swift-logo sticker rushing in your direction. An angry face emerges from behind the laptop:
“It’s crashing!”. Your iOS teammate turns the screen at you, pointing to something that looks like assembly code. It takes a while for you to understand: “Ah! Why didn’t you catch the exception?”. “Why didn’t I catch the exception? Why didn’t I catch the exception? How dare you say that?!”. Fuming, the developer throws — pun intended — the Macbook at you. You are clueless about what just happened.

This article is part of a series, see the other articles here

In order to explain the reason behind the wrath of your Swift colleague, let’s remember something you did last summer: you wrote Java!

import java.io.IOException;

public class JavaReader {
    int read() throws IOException {
        throw new IOException("There's no data");
    }

    public static void main(String... args) {
        final JavaReader reader = new JavaReader();
        try {
            int value = reader.read();
        } catch (IOException ioe) {
            System.err.println(ioe.getMessage());
        }

    }
}

If we rewrite this code again in pure Kotlin fashion it will be something like this:

import java.io.IOException

class KotlinReader {
    fun read(): Int {
        throw IOException()
    }
}

fun main() {
    // This compiles fines, although not advisable
    val value = KotlinReader().run { read() }
}

Did you notice the difference? In Java IOException is a checked exception. That means that you must either handle it with a try-catch block or declare the exception in the function signature. Kotlin went away with checked exceptions. Let’s bring that to the multiplatform world :

// KOTLIN API CODE
import io.ktor.utils.io.errors.IOException

class Reader {
    fun read(): Int {
        throw IOException("No data to read")
    }
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Reader")))
@interface SharedReader : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
- (int32_t)read __attribute__((swift_name("read()")));
@end

// HEADER "TRANSLATED" TO SWIFT 
public class Reader : KotlinBase {
    public init()
    open func read() -> Int32
}

// SWIFT CLIENT CODE
func readData() -> Int32 {
    let reader = Reader()
    do {
        // Warning: No calls to throwing functions occur within 'try' expression
        let value = try reader.read()
        return value
    } catch { // Warning: 'catch' block is unreachable because no errors are thrown in 'do' block
        return -1
    }
}

The Xcode’s warnings seem to not make sense at first. But as soon as readData() is invoked, the iOS app crashes, despite the do-try-catch block.

Function doesn't have or inherit @Throws annotation and thus exception isn't propagated from Kotlin to Objective-C/Swift as NSError.
It is considered unexpected and unhandled instead. Program will be terminated.
Uncaught Kotlin exception: io.ktor.utils.io.errors.IOException: No data to read
    at 0   shared                              0x10d9debf5        kfun:kotlin.Exception#<init>(kotlin.String?;kotlin.Throwable?){} + 133 (/opt/buildAgent/work/acafc8c59a79cc1/kotlin/kotlin-native/runtime/src/main/kotlin/kotlin/Exceptions.kt:25:63)
    at 1   shared                              0x10db71c57        kfun:io.ktor.utils.io.errors.IOException#<init>(kotlin.String;kotlin.Throwable?){} + 119 (/opt/buildAgent/work/8d547b974a7be21f/ktor-io/posix/src/io/ktor/utils/io/errors/IOException.kt:4:58)
    at 2   shared                              0x10db71cbd        kfun:io.ktor.utils.io.errors.IOException#<init>(kotlin.String){} + 93 (/opt/buildAgent/work/8d547b974a7be21f/ktor-io/posix/src/io/ktor/utils/io/errors/IOException.kt:5:50)
    at 3   shared                              0x10d97d4c1        kfun:io.aoriani.kmpapp.Reader#read(){}kotlin.Int + 145 
    at 4   shared                              0x10d981aa7        objc2kotlin_kfun:io.aoriani.kmpapp.Reader#read(){}kotlin.Int + 151 
    at 5   iosApp                              0x10ceefa40        $s6iosApp8readDatas5Int32VyF + 64 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/ContentView.swift:25:32)
    at 6   iosApp                              0x10ceefd64        $s6iosApp11ContentViewVACycfC + 148 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/ContentView.swift:4:0)
    at 7   iosApp                              0x10ceef58c        $s6iosApp6iOSAppV4bodyQrvgAA11ContentViewVyXEfU_ + 44 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/iOSApp.swift:7:4)
    at 8   SwiftUI                             0x113b75a01        get_witness_table 7SwiftUI4ViewRzlAA15ModifiedContentVyxAA25ComplicationIdiomModifierVGAaBHPxAaBHD1__AfA0cH0HPyHCHCTm + 60924 
    at 9   iosApp                              0x10ceef45c        $s6iosApp6iOSAppV4bodyQrvg + 156 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/iOSApp.swift:6:3)
    at 10  iosApp                              0x10ceef838        $s6iosApp6iOSAppV7SwiftUI0B0AadEP4body4BodyQzvgTW + 8 
    at 11  SwiftUI                             0x113284dcf        get_witness_table 7SwiftUI18DynamicViewContentRzlAA08ModifiedE0VyxAA21_TraitWritingModifierVyAA08OnDeleteG3KeyVGGAaBHPxAaBHD1__AiA0dI0HPyHCHCTm + 27673 

Now do you understand why your colleague was mad at you? Even though there was an attempt to catch the Kotlin Exception, it cannot be captured in Swift with the current code.

Okay, let’s follow the recommendation that is in the crash log, and add a @Throws annotation in the same way we would do to support Java interoperability.

// KOTLIN API CODE
import io.ktor.utils.io.errors.IOException

class Reader {
    @Throws(IOException::class)
    fun read(): Int {
        throw IOException("No data to read")
    }
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Reader")))
@interface SharedReader : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));

/**
 * @note This method converts instances of IOException to errors.
 * Other uncaught Kotlin exceptions are fatal.
*/
- (int32_t)readAndReturnError:(NSError * _Nullable * _Nullable)error __attribute__((swift_name("read()"))) __attribute__((swift_error(nonnull_error)));
@end

// HEADER "TRANSLATED" TO SWIFT
public class Reader : KotlinBase {
    public init()
    /**
     * @note This method converts instances of IOException to errors.
     * Other uncaught Kotlin exceptions are fatal.
    */
    open func read() throws -> Int32
}

The new Objective-C signature for our read method may be confusing at first sight for people who are not used to pointers or have never programmed in C. Let’s write a pseudo-Kotlin implementation of it, with some poetic usage of Kotlin Native types:

// This is a pseudo-code!
fun readAndReturnError(error: CPointer<NSError?>?): Int {
    try {
      return read()
    } catch(t: Throwable) {
      // This is not like real CPointers works, 
      // but I am using like this for didatic reasons
      error?.rawValue = t.asNSError()
    }
}

The pretend CPointer above works as a container type, pretty much like Optional, but mutable. If some error happens when the function is called, an instance of NSError will be placed inside the error container. Then the caller can inspect the container. If it contains an NSError that means the function had failed. That is the convention for Cocoa frameworks — the set of Apple’s libraries like UIKit and Foundation, which are used to build iOS and MacOS apps. If some Cocoa method may fail, its last parameter will be a NSErrror** error. Objective-C does have exceptions but they are reserved “for programming or unexpected runtime errors such as out-of-bounds collection access, attempts to mutate immutable objects, sending an invalid message, and losing the connection to the window server”.

The good news is that when methods following the Cocoa convention are bridged to Swift, they are transformed into a method that throws the NSError, as we saw above. Kotlin takes advantage of that, exporting Objective-C methods that follow the Cocoa convention. That way, a Kotlin exception can be propagated and caught on the Swift side. Your iOS teammate can then use the extension kotlinExtension to get the Kotlin exception and downcast it to the expected exceptions:

func readData() -> Int32 {
    let reader = Reader()
    do {
        let value = try reader.read()
        return value
    } catch let error as NSError {
        print("NSError: \(error)")
        
        switch error.kotlinException {
        case let ioException as Ktor_ioIOException:
            print ("Caught IOException")
            print (ioException.message ?? "")
            ioException.printStackTrace()
        case let illegalStateException as KotlinIllegalStateException:
            print ("Caught IllegalStateException")
            print (illegalStateException.message ?? "")
        default:
            print ("Caught something")
        }
        return -1
    }
}

The app no longer crashes, we can capture the exception and print a nice log:

NSError: Error Domain=KotlinException Code=0 "No data to read" UserInfo={NSLocalizedDescription=No data to read, KotlinException=io.ktor.utils.io.errors.IOException: No data to read, KotlinExceptionOrigin=}
Caught IOException
No data to read
io.ktor.utils.io.errors.IOException: No data to read
    at 0   shared                              0x1088de635        kfun:kotlin.Exception#<init>(kotlin.String?;kotlin.Throwable?){} + 133 (/opt/buildAgent/work/acafc8c59a79cc1/kotlin/kotlin-native/runtime/src/main/kotlin/kotlin/Exceptions.kt:25:63)
    at 1   shared                              0x108a716d7        kfun:io.ktor.utils.io.errors.IOException#<init>(kotlin.String;kotlin.Throwable?){} + 119 (/opt/buildAgent/work/8d547b974a7be21f/ktor-io/posix/src/io/ktor/utils/io/errors/IOException.kt:4:58)
    at 2   shared                              0x108a7173d        kfun:io.ktor.utils.io.errors.IOException#<init>(kotlin.String){} + 93 (/opt/buildAgent/work/8d547b974a7be21f/ktor-io/posix/src/io/ktor/utils/io/errors/IOException.kt:5:50)
    at 3   shared                              0x10887b8c1        kfun:io.aoriani.kmpapp.Reader#read(){}kotlin.Int + 145 
    at 4   shared                              0x1088804ab        objc2kotlin_kfun:io.aoriani.kmpapp.Reader#read(){}kotlin.Int + 155 
    at 5   iosApp                              0x107de192b        $s6iosApp8readDatas5Int32VyF + 171 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/ContentView.swift:23:18)
    at 6   iosApp                              0x107de2834        $s6iosApp11ContentViewVACycfC + 148 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/ContentView.swift:4:0)
    at 7   iosApp                              0x107de140c        $s6iosApp6iOSAppV4bodyQrvgAA11ContentViewVyXEfU_ + 44 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/iOSApp.swift:7:4)
    at 8   SwiftUI                             0x10db2ea01        get_witness_table 7SwiftUI4ViewRzlAA15ModifiedContentVyxAA25ComplicationIdiomModifierVGAaBHPxAaBHD1__AfA0cH0HPyHCHCTm + 60924 
    at 9   iosApp                              0x107de12dc        $s6iosApp6iOSAppV4bodyQrvg + 156 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/iOSApp.swift:6:3)
    at 10  iosApp                              0x107de16b8        $s6iosApp6iOSAppV7SwiftUI0B0AadEP4body4BodyQzvgTW + 8 
    at 11  SwiftUI                             0x10d23ddcf        get_witness_table 7SwiftUI18DynamicViewContentRzlAA08ModifiedE0VyxAA21_TraitWritingModifierVyAA08OnDeleteG3KeyVGGAaBHPxAaBHD1__AiA0dI0HPyHCHCTm + 27673 
    at 12  SwiftUI                             0x10db0d8f2        __swift_memcpy49_8 + 14386 
    at 13  SwiftUI                             0x10d23d498        get_witness_table 7SwiftUI18DynamicViewContentRzlAA08ModifiedE0VyxAA21_TraitWritingModifierVyAA08OnDeleteG3KeyVGGAaBHPxAaBHD1__AiA0dI0HPyHCHCTm + 25314 
    at 14  SwiftUI                             0x10db0daaf        __swift_memcpy49_8 + 14831 
    at 15  SwiftUI                             0x10d193ff3        block_destroy_helper.6215 + 63948 
    at 16  AttributeGraph                      0x7ff81fd7a1d6     _ZN2AG5Graph11UpdateStack6updateEv + 536 
    at 17  AttributeGraph                      0x7ff81fd7a9aa     _ZN2AG5Graph16update_attributeENS_4data3ptrINS_4NodeEEEj + 442 
    at 18  AttributeGraph                      0x7ff81fd824f4     _ZN2AG5Graph20input_value_ref_slowENS_4data3ptrINS_4NodeEEENS_11AttributeIDEjPK15AGSwiftMetadataRhl + 394 
    at 19  AttributeGraph                      0x7ff81fd999f0     AGGraphGetValue + 217 
    at 20  SwiftUI                             0x10db0d9d8        __swift_memcpy49_8 + 14616 
    at 21  SwiftUI                             0x10db0da9c        __swift_memcpy49_8 + 14812 
    at 22  SwiftUI                             0x10d193ff3        block_destroy_helper.6215 + 63948 
    at 23  AttributeGraph                      0x7ff81fd7a1d6     _ZN2AG5Graph11UpdateStack6updateEv + 536 
    at 24  AttributeGraph                      0x7ff81fd7a9aa     _ZN2AG5Graph16update_attributeENS_4data3ptrINS_4NodeEEEj + 442 
    at 25  AttributeGraph                      0x7ff81fd824f4     _ZN2AG5Graph20input_value_ref_slowENS_4data3ptrINS_4NodeEEENS_11AttributeIDEjPK15AGSwiftMetadataRhl + 394 
    at 26  AttributeGraph                      0x7ff81fd999f0     AGGraphGetValue + 217 
    at 27  SwiftUI                             0x10db2f887        get_witness_table 7SwiftUI4ViewRzlAA15ModifiedContentVyxAA25ComplicationIdiomModifierVGAaBHPxAaBHD1__AfA0cH0HPyHCHCTm + 64642 
    at 28  SwiftUI                             0x10db2f93b        get_witness_table 7SwiftUI4ViewRzlAA15ModifiedContentVyxAA25ComplicationIdiomModifierVGAaBHPxAaBHD1__AfA0cH0HPyHCHCTm + 64822 
    at 29  SwiftUI                             0x10d133475        objectdestroy.35Tm + 23116 
    at 30  AttributeGraph                      0x7ff81fd7a1d6     _ZN2AG5Graph11UpdateStack6updateEv + 536 
    at 31  AttributeGraph                      0x7ff81fd7a9aa     _ZN2AG5Graph16update_attributeENS_4data3ptrINS_4NodeEEEj + 442 
    at 32  AttributeGraph                      0x7ff81fd81dbe     _ZN2AG5Graph9value_refENS_11AttributeIDEPK15AGSwiftMetadataRh + 122 
    at 33  AttributeGraph                      0x7ff81fd99a35     AGGraphGetValue + 286 
    at 34  SwiftUI                             0x10d23c60a        get_witness_table 7SwiftUI18DynamicViewContentRzlAA08ModifiedE0VyxAA21_TraitWritingModifierVyAA08OnDeleteG3KeyVGGAaBHPxAaBHD1__AiA0dI0HPyHCHCTm + 21588 
    at 35  SwiftUI                             0x10e216492        block_destroy_helper.183 + 44405 
    at 36  SwiftUI                             0x10e211b9e        block_destroy_helper.183 + 25729 
    at 37  SwiftUI                             0x10e212739        block_destroy_helper.183 + 28700 
    at 38  UIKitCore                           0x108f7d798        +[UIScene _sceneForFBSScene:create:withSession:connectionOptions:] + 1393 
    at 39  UIKitCore                           0x109d60465        -[UIApplication _connectUISceneFromFBSScene:transitionContext:] + 1317 
    at 40  UIKitCore                           0x109d60a3d        -[UIApplication workspace:didCreateScene:withTransitionContext:completion:] + 561 
    at 41  UIKitCore                           0x10970636a        -[UIApplicationSceneClientAgent scene:didInitializeWithEvent:completion:] + 349 
    at 42  FrontBoardServices                  0x7ff80549db3a     -[FBSScene _callOutQueue_agent_didCreateWithTransitionContext:completion:] + 414 
    at 43  FrontBoardServices                  0x7ff8054cc7b9     __92-[FBSWorkspaceScenesClient createSceneWithIdentity:parameters:transitionContext:completion:]_block_invoke.187 + 101 
    at 44  FrontBoardServices                  0x7ff8054abb89     -[FBSWorkspace _calloutQueue_executeCalloutFromSource:withBlock:] + 208 
    at 45  FrontBoardServices                  0x7ff8054cc3ae     __92-[FBSWorkspaceScenesClient createSceneWithIdentity:parameters:transitionContext:completion:]_block_invoke + 343 
    at 46  libdispatch.dylib                   0x108334f5a        _dispatch_client_callout + 7 
    at 47  libdispatch.dylib                   0x1083388d1        _dispatch_block_invoke_direct + 495 
    at 48  FrontBoardServices                  0x7ff8054f2bb7     __FBSSERIALQUEUE_IS_CALLING_OUT_TO_A_BLOCK__ + 29 
    at 49  FrontBoardServices                  0x7ff8054f2aad     -[FBSSerialQueue _targetQueue_performNextIfPossible] + 173 
    at 50  FrontBoardServices                  0x7ff8054f2bdf     -[FBSSerialQueue _performNextFromRunLoopSource] + 18 
    at 51  CoreFoundation                      0x7ff800387fe4     __CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE0_PERFORM_FUNCTION__ + 16 
    at 52  CoreFoundation                      0x7ff800387f23     __CFRunLoopDoSource0 + 156 
    at 53  CoreFoundation                      0x7ff800387780     __CFRunLoopDoSources0 + 307 
    at 54  CoreFoundation                      0x7ff800381e22     __CFRunLoopRun + 926 
    at 55  CoreFoundation                      0x7ff8003816a6     CFRunLoopRunSpecific + 559 
    at 56  GraphicsServices                    0x7ff809cb1289     GSEventRunModal + 138 
    at 57  UIKitCore                           0x109d5ead2        -[UIApplication _run] + 993 
    at 58  UIKitCore                           0x109d639ee        UIApplicationMain + 122 
    at 59  SwiftUI                             0x10df4c666        __swift_memcpy93_8 + 11935 
    at 60  SwiftUI                             0x10df4c513        __swift_memcpy93_8 + 11596 
    at 61  SwiftUI                             0x10d5b07e8        __swift_memcpy195_8 + 12254 
    at 62  iosApp                              0x107de164d        $s6iosApp6iOSAppV5$mainyyFZ + 29 (/Users/aoriani/Development/Multiplatform/KmpApp/iosApp/iosApp/iOSApp.swift:<unknown>)
    at 63  iosApp                              0x107de16d8        main + 8 
    at 64  dyld                                0x1080292be        0x0 + 4429353662 
    at 65  ???                                 0x1159a652d        0x0 + 4657407277

Moral of the story: Always annotate your Kotlin APIs with @Throws listing all possible exceptions that could be thrown by your code, so your iOS teammate can catch them.

In this chapter, we learned we must declare exceptions in the Kotlin APIs so the Kotlin Native compiler will generate the code that will allow them to be caught in Swift. See you in the next chapter! Meanwhile, check the other episodes of this series:

Writing Swift-friendly Kotlin Multiplatform APIs

References:

• Interoperability with Swift/Objective-C — Errors and exceptions https://kotlinlang.org/docs/native-objc-interop.html#errors-and-exceptions
• ROTOLO, Paolo and LABELLARTE, Anna — Kotlin Multiplatform for Android & iOS library developers: Tips for writing Kotlin Multiplatform Android/iOS libraries https://fosdem.org/2023/schedule/event/kmp_for_android_and_ios_library_developers/
• Apple’s Cocoa Documentation — Using and Creating Error Objects — https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ErrorHandlingCocoa/CreateCustomizeNSError/CreateCustomizeNSError.html
• Swift Evolution — Improved NSError Bridging https://github.com/apple/swift-evolution/blob/main/proposals/0112-nserror-bridging.md
• The Swift Programming Language (5.9 beta) — Error Handling https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling/
• Handling Cocoa Errors in Swift - https://developer.apple.com/documentation/swift/handling-cocoa-errors-in-swift
• Name Translation from C to Swift - https://github.com/apple/swift/blob/main/docs/CToSwiftNameTranslation.md#error-handling
• Introduction to Exception Programming Topics for Cocoa -https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Exceptions/Exceptions.html

Writing Swift-friendly Kotlin Multiplatform APIs — Part V: Exceptions was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to code libraries that your iOS teammates will not frown upon using them. In this chapter: providing convenience.

In the previous chapter, we saw that using interfaces sometimes renders unexpected results. In this one, we will deal with situations in which the exported API is not too bad but could be improved substantially.

This article is part of a series, see the other articles here

From this chapter on, there will be a small change in the format. If you read the extra article for this series, you know that is possible to “translate” the Objective-C header to Swift. So from now on, besides the Kotlin API and its correspondent Objective-C header, I will also provide the header’s translation to Swift, so we can have a better understanding of how the Kotlin code will be seen in Xcode when editing a Swift file.

Extensions

Let’s start with a simple Person interface and an extension to return the full name.

// KOTLIN API CODE
interface Person {
    val firstName: String
    val lastName: String
}

fun Person.fullName() = "$firstName $lastName"

// EXPORTED OBJ-C HEADER
__attribute__((swift_name("Person")))
@protocol SharedPerson
@required
@property (readonly) NSString *firstName __attribute__((swift_name("firstName")));
@property (readonly) NSString *lastName __attribute__((swift_name("lastName")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ExampleKt")))
+ (NSString *)fullName:(id<SharedPerson>)receiver __attribute__((swift_name("fullName(_:)")));
@end

// HEADER "TRANSLATED" TO SWIFT
public protocol Person {
    var firstName: String { get }
    var lastName: String { get }
}

public class ExampleKt : KotlinBase {
    open class func fullName(_ receiver: Person) -> String
}

// SWIFT CLIENT CODE
class SwiftPerson: Person {
    let firstName: String
    let lastName: String
        
    init(firstName: String, lastName: String) {
        self.firstName = firstName
        self.lastName = lastName
    }
}
let swiftPerson = SwiftPerson(firstName: "Bruce", lastName: "Wayne")

// Java déjà vu?
print(ExampleKt.fullName(swiftPerson))

How to improve it

Well, it is not bad. It is pretty much like we would call the same extension from Java. But would not it be better if we could use the extension in Swift as we would do in Kotlin? If you read the previous chapter you may be thinking right now: “Make it a class!”. And yes, you are right.

// KOTLIN API CODE
abstract class Person(
    val firstName: String,
    val lastName: String
)

fun Person.fullName() = "$firstName $lastName"

// EXPORTED OBJ-C HEADER
__attribute__((swift_name("Person")))
@interface SharedPerson : SharedBase
- (instancetype)initWithFirstName:(NSString *)firstName lastName:(NSString *)lastName __attribute__((swift_name("init(firstName:lastName:)"))) __attribute__((objc_designated_initializer));
@property (readonly) NSString *firstName __attribute__((swift_name("firstName")));
@property (readonly) NSString *lastName __attribute__((swift_name("lastName")));
@end

@interface SharedPerson (Extensions)
- (NSString *)fullName __attribute__((swift_name("fullName()")));
@end

// HEADER "TRANSLATED" TO SWIFT
open class Person : KotlinBase {
    public init(firstName: String, lastName: String)
    open var firstName: String { get }
    open var lastName: String { get }
}

extension Person {
    open func fullName() -> String
}

// SWIFT CLIENT CODE
class SwiftPerson: Person {}
let swiftPerson = SwiftPerson(firstName: "Bruce", lastName: "Wayne")
print(swiftPerson.fullName())

The Kotlin extension is now exported as an Objective-C extension. In fact, if you read the documentation, there are a couple of other types, other than interfaces, for which Kotlin extensions will not be exported as Objective-C extensions:

• Kotlin String type
• Kotlin collection types and subtypes
• Kotlin interface types
• Kotlin primitive types
• Kotlin inline classes
• Kotlin Any type
• Kotlin function types and subtypes
• Objective-C classes and protocols, but MOKO KSwift may help you with these ones.

Refining APIs in Swift

Ranges and destructuring declarations are pretty handy features in Kotlin. They do also exist in Swift, but, because they do not exist in Objective-C, they are lost in translation as we see in the code below:

// KOTLIN API CODE
data class Point(val x: Int, val y: Int) {
    fun isInRange(xRange: IntRange, yRange: IntRange): Boolean {
        return x in xRange && y in yRange
    }
}

// KOTLIN CLIENT CODE
fun test() {
    val point = Point(x = 5, y = 7)
    val (x,y) = point
    point.isInRange(1..2, 3..4)
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Point")))
@interface SharedPoint : SharedBase
- (instancetype)initWithX:(int32_t)x y:(int32_t)y __attribute__((swift_name("init(x:y:)"))) __attribute__((objc_designated_initializer));
- (SharedPoint *)doCopyX:(int32_t)x y:(int32_t)y __attribute__((swift_name("doCopy(x:y:)")));
- (BOOL)isEqual:(id _Nullable)other __attribute__((swift_name("isEqual(_:)")));
- (NSUInteger)hash __attribute__((swift_name("hash()")));
- (BOOL)isInRangeXRange:(SharedKotlinIntRange *)xRange yRange:(SharedKotlinIntRange *)yRange __attribute__((swift_name("isInRange(xRange:yRange:)")));
- (NSString *)description __attribute__((swift_name("description()")));
@property (readonly) int32_t x __attribute__((swift_name("x")));
@property (readonly) int32_t y __attribute__((swift_name("y")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class Point : KotlinBase {
    public init(x: Int32, y: Int32)
    open func doCopy(x: Int32, y: Int32) -> Point
    open func isEqual(_ other: Any?) -> Bool
    open func hash() -> UInt
    open func isInRange(xRange: KotlinIntRange, yRange: KotlinIntRange) -> Bool
    open func description() -> String
    open var x: Int32 { get }
    open var y: Int32 { get }
}

// SWIFT CLIENT CODE
let point = Point(x: 5, y: 7)
let x = point.x
let y = point.y
let isInRange = point.isInRange(
    xRange: KotlinIntRange(start: 0, endInclusive: 5),
    yRange: KotlinIntRange(start: 2, endInclusive: 5)
)

How to improve it

Adding the @ShouldRefineInSwift to a function or property will cause the exported header for it to have the swift_private attribute. The symbol will then be hidden from Xcode auto-completion and its name will be prepended by two underscores (__ ) in Swift.

We can then define Swift extensions that will wrap the Kotlin API providing more convenient signatures. In this example, we provided an extension to convert the Point data class to a tuple, and to “rewrite” the method isInRange to accept Swift ranges, instead of forcing our iOS friends to cumbersomely create instances of IntRange.

Note that in the translation of the header from Objective-C to Swift, the isInRange method disappeared. The Swift extension had to be accessed as __is(inRangeXRange:yRange).

// KOTLIN API CODE
data class Point(val x: Int, val y: Int) {
    @OptIn(ExperimentalObjCRefinement::class)
    @ShouldRefineInSwift
    fun isInRange(xRange: IntRange, yRange: IntRange): Boolean {
        return x in xRange && y in yRange
    }
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Point")))
@interface SharedPoint : SharedBase
- (instancetype)initWithX:(int32_t)x y:(int32_t)y __attribute__((swift_name("init(x:y:)"))) __attribute__((objc_designated_initializer));
- (SharedPoint *)doCopyX:(int32_t)x y:(int32_t)y __attribute__((swift_name("doCopy(x:y:)")));
- (BOOL)isEqual:(id _Nullable)other __attribute__((swift_name("isEqual(_:)")));
- (NSUInteger)hash __attribute__((swift_name("hash()")));
- (BOOL)isInRangeXRange:(SharedKotlinIntRange *)xRange yRange:(SharedKotlinIntRange *)yRange __attribute__((swift_private));
- (NSString *)description __attribute__((swift_name("description()")));
@property (readonly) int32_t x __attribute__((swift_name("x")));
@property (readonly) int32_t y __attribute__((swift_name("y")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class Point : KotlinBase {
    public init(x: Int32, y: Int32)
    open func doCopy(x: Int32, y: Int32) -> Point
    open func isEqual(_ other: Any?) -> Bool
    open func hash() -> UInt
    open func description() -> String
    open var x: Int32 { get }
    open var y: Int32 { get }
}

// CONVENIENT SWIFT EXTENSION
extension Point {
    var tuple: (Int32, Int32) { (x, y) }
    
    func isInRange(xRange: ClosedRange<Int>, yRange: ClosedRange<Int>) -> Bool {
        return __is(
            inRangeXRange: KotlinIntRange(start: Int32(xRange.lowerBound), endInclusive: Int32(xRange.upperBound)),
            yRange: KotlinIntRange(start: Int32(yRange.lowerBound), endInclusive: Int32(yRange.upperBound))
        )
    }
}

// SWIFT CLIENT CODE
let point = Point(x: 5, y: 7)
let (x, y) = point.tuple
let isInRange = point.isInRange(xRange:  0...5, yRange: 2...5)

Defining iOS-only extensions

You still can provide some convenience to iOS developers without touching Xcode. Besides defining actual implementation for the expect declarations, you can also take advantage of the fact that you have access to Apple’s Objective-C frameworks in iosMain. You can define functions and extensions that will only be available to iOS clients.

In the following example, we have a baseUrl defined in commonMain using Ktor’s Url . For Android, we defined an Url.toURL extension that returns java.net.URL. For iOS we defined the same extension but this time it returns NSURLfrom the Foundation framework. Conveniently NSURL is bridged to Swift’s URL. Note that it would be impossible to define such an extension in commonMain for two reasons:

• They return platform-specific types which are not available in commonMain for obvious reasons;
• You cannot overload methods to have the same signature but return different types.

// KOTLIN API CODE

// commonMain
import io.ktor.http.Url

object ServiceConfig {
    val baseUrl = Url("https://api.server.com/service")
}

// androidMain
import io.ktor.http.Url
import java.net.URL

fun Url.toURL(): URL = URL(this.toString())

// iosMain
import io.ktor.http.Url
import platform.Foundation.NSURL

fun Url.toURL(): NSURL  = NSURL(string = toString())

// Android Client code 
val url = ServiceConfig.baseUrl.toURL()
val connection = url.openConnection()

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ServiceConfig")))
@interface SharedServiceConfig : SharedBase
+ (instancetype)alloc __attribute__((unavailable));
+ (instancetype)allocWithZone:(struct _NSZone *)zone __attribute__((unavailable));
+ (instancetype)serviceConfig __attribute__((swift_name("init()")));
@property (class, readonly, getter=shared) SharedServiceConfig *shared __attribute__((swift_name("shared")));
@property (readonly) SharedKtor_httpUrl *baseUrl __attribute__((swift_name("baseUrl")));
@end

@interface SharedKtor_httpUrl (Extensions)
- (NSURL *)toURL __attribute__((swift_name("toURL()")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class ServiceConfig : KotlinBase {
    public convenience init()
    open class var shared: ServiceConfig { get }
    open var baseUrl: Ktor_httpUrl { get }
}

extension Ktor_httpUrl {
    open func toURL() -> URL
}

// SWIFT CLIENT CODE
let url = Service.shared.baseUrl.toURL()
let session = URLSession(configuration: .default)
session.dataTask(with: url) {
...

Default Arguments

Default arguments were one of the nicest additions to Kotlin. We no longer need to worry about telescoping constructors, creating builders, etc… Sadly, they are not supported by Objective-C.

// KOTLIN API CODE
fun compareString(a: String, b: String, ignoreCase: Boolean = false): Boolean {
    return a.equals(b, ignoreCase = ignoreCase)
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ExampleKt")))
@interface SharedExampleKt : SharedBase
+ (BOOL)compareStringA:(NSString *)a b:(NSString *)b ignoreCase:(BOOL)ignoreCase __attribute__((swift_name("compareString(a:b:ignoreCase:)")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class ExampleKt : KotlinBase {
    open class func compareString(a: String, b: String, ignoreCase: Bool) -> Bool
}

// SWIFT CLIENT CODE
let result1 = ExampleKt.compareString(a: "HELLO", b: "hello", ignoreCase: true)
// Compile error: Missing argument for parameter 'ignoreCase' in call
// let result2 = ExampleKt.compareString(a: "Roma", b: "Londres")

How to improve it

Unfortunately, there is no annotation for Kotlin Multiplatform that is the equivalent of @JvmOverloads yet. So you have to provide the overloads yourself

// KOTLIN API CODE
fun compareString(a: String, b: String, ignoreCase: Boolean): Boolean {
    return a.equals(b, ignoreCase = ignoreCase)
}

fun compareString(a: String, b: String): Boolean {
    return compareString(a, b, false)
}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ExampleKt")))
@interface SharedExampleKt : SharedBase
+ (BOOL)compareStringA:(NSString *)a b:(NSString *)b __attribute__((swift_name("compareString(a:b:)")));
+ (BOOL)compareStringA:(NSString *)a b:(NSString *)b ignoreCase:(BOOL)ignoreCase __attribute__((swift_name("compareString(a:b:ignoreCase:)")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class ExampleKt : KotlinBase {
    open class func compareString(a: String, b: String) -> Bool
    open class func compareString(a: String, b: String, ignoreCase: Bool) -> Bool
}

// SWIFT CLIENT CODE
let result1 = ExampleKt.compareString(a: "HELLO", b: "hello", ignoreCase: true)
let result2 = ExampleKt.compareString(a: "Roma", b: "Londres")

Alternatively, you can try SKIE from Touchlabs, which does provide compile-time support for default parameters.

Primitive? versus Primitive!

Objective-C does not have box types matching primitive types one-to-one like Java and Kotlin do. Objective-C does have NSNumber, NSInteger, and CGFloat, but they are not exactly type boxes. NSNumber, for instance, “doesn’t provide enough information about a wrapped primitive value type, i.e. NSNumber is statically not known to be Byte, Boolean, or Double”. Kotlin will use a primitive type when possible. However, when a box type is required, like in the case of a nullable return, Kotlin will use its own type box classes as we see below. Those types inherit from NSNumber. For function types, primitives will always be boxed. Curiously there is no KotlinChar as of Kotlin 1.9.0, so the character function below returns id _Nullable in Obj-C and Any? in Swift, id est, the type information was lost.

The solution is to either avoid nullables or use @ShouldRefineInSwift and wrap the function with a Swift extension to allow iOS devs to use more convenient types.

// KOTLIN API CODE
fun boolean(a: Boolean): Boolean? = a
fun integer(a: Int): Int? = a
fun character(a: Char): Char? = a
fun float(a: Float): Float? = a
fun double(a: Double): Double? = a
fun long(a: Long): Long? = a
fun short(a: Short): Short? = a
fun byte(a: Byte): Byte? = a
fun intFunc(a: (Int) -> Int?) {}

// EXPORTED OBJ-C HEADER
__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("ExampleKt")))
@interface SharedExampleKt : SharedBase
+ (SharedBoolean * _Nullable)booleanA:(BOOL)a __attribute__((swift_name("boolean(a:)")));
+ (SharedByte * _Nullable)byteA:(int8_t)a __attribute__((swift_name("byte(a:)")));
+ (id _Nullable)characterA:(unichar)a __attribute__((swift_name("character(a:)")));
+ (SharedDouble * _Nullable)doubleA:(double)a __attribute__((swift_name("double(a:)")));
+ (SharedFloat * _Nullable)floatA:(float)a __attribute__((swift_name("float(a:)")));
+ (void)intFuncA:(SharedInt * _Nullable (^)(SharedInt *))a __attribute__((swift_name("intFunc(a:)")));
+ (SharedInt * _Nullable)integerA:(int32_t)a __attribute__((swift_name("integer(a:)")));
+ (SharedLong * _Nullable)longA:(int64_t)a __attribute__((swift_name("long(a:)")));
+ (SharedShort * _Nullable)shortA:(int16_t)a __attribute__((swift_name("short(a:)")));
@end

// HEADER "TRANSLATED" TO SWIFT
public class ExampleKt : KotlinBase {
    open class func boolean(a: Bool) -> KotlinBoolean?
    open class func byte(a: Int8) -> KotlinByte?
    open class func character(a: unichar) -> Any?
    open class func double(a: Double) -> KotlinDouble?
    open class func float(a: Float) -> KotlinFloat?
    open class func intFunc(a: @escaping (KotlinInt) -> KotlinInt?)
    open class func integer(a: Int32) -> KotlinInt?
    open class func long(a: Int64) -> KotlinLong?
    open class func short(a: Int16) -> KotlinShort?
}

In this chapter, we learned how to tenderize your APIs so they can be savored by your Xcode friends. Be sure to check the other articles in the series:

Writing Swift-friendly Kotlin Multiplatform APIs

References

• ROTOLO, Paolo and LABELLARTE, Anna — Kotlin Multiplatform for Android & iOS library developers: Tips for writing Kotlin Multiplatform Android/iOS libraries https://fosdem.org/2023/schedule/event/kmp_for_android_and_ios_library_developers/
• Interoperability with Swift/Objective-C https://kotlinlang.org/docs/native-objc-interop.html

Writing Swift-friendly Kotlin Multiplatform APIs — Part IV was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Learn how to code libraries that your iOS teammates will not frown upon using them. In this extra: translating Obj-C to Swift

This is an extra article in the series. You can find all the articles here.

I normally publish one chapter per week, but I believe that is essential to introduce this topic now because it will be useful for the next chapters. Besides, I only learned about it after I published part III (I have up to part VIII planned so far).

If you have been following this series, you are used to the format. I first present the Kotlin code followed by the exported Objective-C header. The reason for that is twofold:

• Currently, Kotlin is only interoperable with Objective-C. The fact that you can use a KMP API in Swift is a side-effect of Swift's interoperability with Objective-C.
• The exported Objective-C header is the first generated artifact that we can inspect in order to predict if our API will present any usability concerns to our iOS teammates.

However, the Objective-C header is hard to read, especially when one doesn't know the language. On top of that, in the same way we predict that soon there will be Android developers who do not know Java, I expect that there will be iOS devs who will never use Objective-C. Would not be nice if we could “convert” that header to Swift?

In my research for these articles, I found Salomon BRYS’s (Kodein author) talk at the last KotlinConf, where he briefly showed that it was possible. By the way, his lecture is a great complement to this series. I also found this article from Brian Amstrong which tells the process in more detail and uses a more simplified yaml file. I will summarize the process here, assuming you are using a Mac:

1. Install sourcekitten and jq:

$ brew install sourcekitten jq

2. Create the following yaml file:

key.request: source.request.editor.open.interface.header
key.name: "1F3F8533-DD3F-4B63-8B4F-80BA94CCF3CA"
# This should be the path to your header file 
key.filepath: "/Users/aoriani/Development/Multiplatform/KmpApp/shared/build/fat-framework/debug/shared.framework/Headers/shared.h"
key.compilerargs:
    - "-x"
    - "objective-c"
# This should be the path to your header file
    - "/Users/aoriani/Development/Multiplatform/KmpApp/shared/build/fat-framework/debug/shared.framework/Headers/shared.h"
    - "-isysroot"
# This should be the path to the Mac SDK and it will depend on your Xcode version
    - "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX13.sdk"

3. Run sourcekitten

$ sourcekitten request --yaml request.yaml | jq -r '.["key.sourcetext"]' > Shared.swift

If you know how to convert the generated “Swift header” to some sort of documentation, like Javadoc, Doxygen, Dokka, etc, please let me know. I am really interested in providing API documentation to my Swift developers.

Revisiting the problem with sets and interfaces

Now that we learned this new technique, let us see how much easier it would be to spot the problem with interfaces and sets that we faced in the Part III article:

// KOTLIN API CODE
interface Option {
   val id: String
}

class Order {
   fun setOptions(options: Set<Option>) {}
}

// EXPORTED OBJ-C HEADER
__attribute__((swift_name("Option")))
@protocol SharedOption
@required
@property (readonly) NSString *id __attribute__((swift_name("id")));
@end

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Order")))

@interface SharedOrder : SharedBase
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
- (void)setOptionsOptions:(NSSet<id<SharedOption>> *)options __attribute__((swift_name("setOptions(options:)")));
@end

// HEADER CONVERTED TO SWIFT
public protocol Option {
    var id: String { get }
}

public class Order : KotlinBase {
    public init()
    open func setOptions(options: Set<AnyHashable>)
}

Before we had to look at the type of the parameter optionin the Objective-C header. The type-argument for NSSet being id<SharedOption> was a bit suspicious. But now with the header converted to Swift, the problem is pretty obvious: we expected Set<Option> but we got Set<AnyHashable>.

I hope you have enjoyed this extra article. In case you want to see all the other articles of the series here they are:

Writing Swift-friendly Kotlin Multiplatform APIs

References

• BRYS, Salomon — Kotlin/Multiplatform for iOS developers: state & future — In KotlinConf ’23 Amsterdam https://kotlinconf.com/talks/387260/
• ARMSTRONG, Brian — Generating Swift Documentation From Objective-C https://quiet.github.io/quiet-blog/2018/08/13/Objective-C-Swift-Documentation.html

Writing Swift-Friendly Kotlin Multiplatform APIs — Extra was originally published in Towards Dev on Medium, where people are continuing the conversation by highlighting and responding to this story.