RunCatching for safe execution in Kotlin - Deep Dive

Overview - Runcatching For Safe Execution

What is it?

Runcatching is a way in Kotlin to run a block of code safely by catching any errors that might happen. Instead of crashing your program when something goes wrong, it wraps the result or the error in a special container. This helps you handle success and failure in a clean and simple way without using try-catch blocks everywhere.

Why it matters

Without runcatching, programs can crash unexpectedly when errors happen, making apps unreliable and frustrating for users. Runcatching helps keep programs running smoothly by managing errors gracefully. This means better user experience and easier code maintenance because error handling is clear and consistent.

Where it fits

Before learning runcatching, you should understand basic Kotlin syntax and how exceptions work with try-catch. After mastering runcatching, you can explore more advanced error handling patterns like sealed classes for results, coroutines with error handling, and functional programming concepts like Either or Result types.

Mental Model

Core Idea

Runcatching runs code and safely captures success or failure as a result object, so you can handle both without crashing.

Think of it like...

Imagine you are opening a gift box that might be empty or broken. Instead of just opening it and risking disappointment, you put a protective cover around it that tells you if the gift is good or if there was a problem, so you can decide what to do next.

┌───────────────┐
│   runcatching │
└──────┬────────┘
       │ runs code
       ▼
┌───────────────┐
│   Success     │
│  (value)      │
└───────────────┘
       or
┌───────────────┐
│   Failure     │
│  (exception)  │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Kotlin Exceptions

Concept: Learn what exceptions are and how Kotlin handles them with try-catch blocks.

In Kotlin, when something goes wrong during program execution, an exception is thrown. You can catch these exceptions using try-catch blocks to prevent your program from crashing. For example: try { val result = 10 / 0 } catch (e: ArithmeticException) { println("Cannot divide by zero") }

Result

The program prints "Cannot divide by zero" instead of crashing.

Understanding exceptions and try-catch is essential because runcatching builds on this idea to simplify error handling.

2

Foundation

Introducing Kotlin's Result Type

Concept: Learn about Kotlin's Result type that holds either a success value or an exception.

Kotlin has a built-in Result class that can hold a successful value or an error. This helps represent outcomes without throwing exceptions immediately. You can create a Result manually: val success = Result.success(42) val failure = Result.failure(Exception("Oops"))

Result

You get objects that clearly say if the operation succeeded or failed.

Knowing Result is key because runcatching returns this type, making error handling explicit and safe.

3

Intermediate

Using runcatching to Run Code Safely

🤔Before reading on: do you think runcatching catches all exceptions or only some? Commit to your answer.

Concept: Learn how to use runcatching to run code blocks and automatically catch any exceptions.

Kotlin provides the runCatching function that runs a block of code and returns a Result. If the block succeeds, it returns Result.success with the value. If an exception happens, it returns Result.failure with the exception. Example: val result = runCatching { val number = "123a".toInt() // This will throw NumberFormatException number * 2 } println(result) // Prints failure with exception

Result

The result is a failure object holding the NumberFormatException instead of crashing.

Understanding that runcatching catches all exceptions inside the block helps you write safer code without try-catch clutter.

4

Intermediate

Handling Results with onSuccess and onFailure

🤔Before reading on: do you think onSuccess and onFailure run immediately or only when called? Commit to your answer.

Concept: Learn how to react to success or failure using onSuccess and onFailure methods on Result.

After getting a Result from runcatching, you can use onSuccess to run code if it succeeded, and onFailure to handle errors. Example: runCatching { "100".toInt() } .onSuccess { println("Success: $it") } .onFailure { println("Error: ${it.message}") } runCatching { "abc".toInt() } .onSuccess { println("Success: $it") } .onFailure { println("Error: ${it.message}") }

Result

First prints "Success: 100", second prints "Error: For input string: \"abc\"".

Knowing these handlers lets you separate success and error logic cleanly without nested try-catch.

5

Intermediate

Transforming Results with map and recover

🤔Before reading on: do you think map changes failure results or only success? Commit to your answer.

Concept: Learn how to transform successful results or recover from failures using map and recover.

You can use map to change the success value without touching failures. recover lets you provide a fallback value if there was an error. Example: val result = runCatching { "50".toInt() } .map { it * 2 } // doubles the number if success .recover { 0 } // returns 0 if failure println(result.getOrNull()) // prints 100 val failed = runCatching { "fail".toInt() } .map { it * 2 } .recover { 0 } println(failed.getOrNull()) // prints 0

Result

Success values are transformed; failures can be replaced with defaults.

Understanding map and recover helps you chain operations safely and handle errors gracefully.

6

Advanced

Combining Multiple runcatching Results

🤔Before reading on: do you think you can combine multiple Results directly or need special handling? Commit to your answer.

Concept: Learn how to work with multiple Result objects and combine their outcomes safely.

When you have several operations that return Result, you can combine them by checking each result's success or failure. Kotlin does not provide built-in combinators, but you can use flatMap or custom functions. Example: val r1 = runCatching { 10 } val r2 = runCatching { 0 } val combined = r1.flatMap { a -> r2.flatMap { b -> runCatching { a / b } } // catches ArithmeticException } println(combined) // failure due to division by zero

Result

The combined result is a failure if any step fails, preserving error info.

Knowing how to chain and combine Results prevents silent errors and keeps error context intact.

7

Expert

Internal Behavior and Exception Safety of runcatching

🤔Before reading on: do you think runcatching catches only unchecked exceptions or all throwables? Commit to your answer.

Concept: Explore how runcatching works internally to catch exceptions and why it is safe and reliable.

runCatching runs the given block inside a try-catch that catches all Throwable objects, including checked and unchecked exceptions. It then wraps the result or exception in a Result object. This design ensures no exceptions escape unexpectedly. Internally, it uses Kotlin's inline functions and contracts to optimize performance and maintain stack traces. Example of internal behavior: inline fun runCatching(block: () -> R): Result { return try { Result.success(block()) } catch (e: Throwable) { Result.failure(e) } }

Result

All exceptions are safely caught and wrapped, preventing crashes.

Understanding that runcatching catches all Throwables explains why it is a robust tool for safe execution.

Under the Hood

runcatching executes the code block inside a try-catch that catches every Throwable, including errors and exceptions. It then creates a Result object that holds either the successful value or the caught exception. This Result is a sealed class that safely encapsulates outcomes, allowing further operations without risking uncaught exceptions.

Why designed this way?

Kotlin designed runcatching to simplify error handling by avoiding verbose try-catch blocks scattered in code. Wrapping results in a single container encourages functional-style chaining and clear separation of success and failure. Catching all Throwables ensures no unexpected crashes, improving reliability and developer experience.

┌───────────────┐
│ runCatching() │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ try { block } │
└──────┬────────┘
       │
  ┌────┴─────┐
  │          │
  ▼          ▼
Success    Exception
  │          │
  ▼          ▼
Result.success  Result.failure
  │          │
  └────┬─────┘
       ▼
   Returned Result

Myth Busters - 4 Common Misconceptions

Quick: Does runCatching catch only exceptions or all Throwables? Commit to yes or no.

Common Belief: runCatching only catches exceptions, so errors like OutOfMemoryError will crash the program.

Reality: runCatching catches all Throwables, including errors and exceptions, so it can catch serious errors too.

Why it matters: Believing it catches only exceptions can lead to unexpected crashes if errors are not handled, but runCatching actually prevents this by catching everything.

Quick: Does runCatching execute the block immediately or lazily? Commit to your answer.

Common Belief: runCatching delays execution until you ask for the result, like a lazy operation.

Reality: runCatching executes the block immediately when called, not lazily.

Why it matters: Thinking it is lazy can cause confusion about when side effects happen, leading to bugs in program flow.

Quick: Can you use runCatching to handle asynchronous exceptions? Commit to yes or no.

Common Belief: runCatching can catch exceptions thrown asynchronously, like in coroutines or threads.

Reality: runCatching only catches exceptions thrown inside its block synchronously; asynchronous exceptions must be handled differently.

Why it matters: Misusing runCatching for async errors can cause missed exceptions and unstable programs.

Quick: Does onFailure consume the exception preventing further handling? Commit to yes or no.

Common Belief: Calling onFailure stops the exception from propagating or being handled elsewhere.

Reality: onFailure only observes the failure; it does not consume or stop propagation.

Why it matters: Misunderstanding this can lead to incorrect assumptions about error flow and missed error handling.

Expert Zone

1

runCatching catches all Throwables, including serious errors, which means it can hide critical problems if overused without care.

2

The Result type returned by runCatching is inline and optimized, but improper chaining can lead to loss of exception stack traces if not handled carefully.

3

Using runCatching in performance-critical code requires understanding its inline nature and how it affects inlining and stack traces.

When NOT to use

Avoid using runCatching for asynchronous code like coroutines or threads where exceptions happen outside the block. Instead, use coroutine exception handlers or thread uncaught exception handlers. Also, do not use runCatching to suppress critical errors like OutOfMemoryError in production, as it may hide serious issues.

Production Patterns

In production, runCatching is often used to wrap risky operations like network calls, file I/O, or parsing user input. Developers chain map, recover, and fold to transform results and provide fallback values. It is also used in combination with sealed classes to model domain-specific success and failure states cleanly.

Connections

Functional Programming's Either Type

runCatching's Result is similar to Either, representing success or failure as a value.

Understanding runCatching helps grasp functional error handling patterns where errors are values, not exceptions.

Exception Handling in Java

runCatching simplifies Java-style try-catch by wrapping exceptions in a container instead of throwing.

Knowing Java exceptions clarifies why Kotlin introduced runCatching to reduce boilerplate and improve safety.

Real-life Risk Management

runCatching models how people prepare for uncertain outcomes by planning for success or failure.

Seeing error handling as risk management helps appreciate why capturing all outcomes explicitly improves software reliability.

Common Pitfalls

#1 Ignoring the failure result and assuming success.

Wrong approach:

val result = runCatching { "abc".toInt() }
println(result.getOrNull()!! * 2) // crashes with NullPointerException

Correct approach:

val result = runCatching { "abc".toInt() }
result.onSuccess { println(it * 2) }
.onFailure { println("Error: ${it.message}") }

Root cause:

Assuming the result always contains a value without checking for failure leads to runtime crashes.

#2 Using runCatching to catch asynchronous exceptions.

Wrong approach:

runCatching {
Thread { throw Exception("Async error") }.start()
}

Correct approach:

val thread = Thread {
try {
throw Exception("Async error")
} catch (e: Exception) {
println("Caught async error: ${e.message}")
}
}
thread.start()

Root cause:

runCatching only catches exceptions thrown inside its block synchronously, not in other threads.

#3 Swallowing critical errors by catching all Throwables without rethrowing.

Wrong approach:

runCatching {
// risky code
}.onFailure { /* ignore all errors */ }

Correct approach:

runCatching {
// risky code
}.onFailure {
if (it is VirtualMachineError) throw it
else println("Handled error: ${it.message}")
}

Root cause:

Not distinguishing between recoverable exceptions and critical errors can hide serious problems.

Key Takeaways

runCatching in Kotlin runs code blocks safely by catching all exceptions and wrapping the outcome in a Result object.

This approach avoids program crashes and makes error handling explicit and composable with methods like onSuccess, onFailure, map, and recover.

Understanding that runCatching catches all Throwables, including serious errors, is crucial to using it responsibly.

runCatching executes code immediately and only catches synchronous exceptions inside its block.

Proper use of runCatching improves code clarity, reliability, and aligns with functional programming principles of handling success and failure as values.