⚠️ Disclaimer — Preview feature

• Yêu cầu C# 15 / .NET 11 Preview 2 trở lên.
• Tính đến .NET 11 Preview 2, UnionAttribute và IUnion chưa được include trong runtime. Muốn dùng phải tự khai báo trong project (xem mục Union implementation trong docs).
• Đây là preview — API và behavior có thể thay đổi trước khi ship chính thức.

💠 1. Bản chất

• Union types trong C# là union of types thông qua một wrapper type.

• Nó là type union — KHÔNG phải tagged union hay discriminated union theo nghĩa truyền thống. Trích trực tiếp từ proposal:

  "The proposed unions in C# are unions of types and not 'discriminated' or 'tagged'."

  Sự khác biệt:

  • Discriminated union (F#, Haskell): dùng một trường discriminator/tag riêng biệt để phân biệt case.
  • Type union trong C#: dùng chính runtime type của Value làm discriminator — không có trường tag riêng.
  • Về hành vi, nó tương tự discriminated union ở chỗ pattern matching có thể biết chính xác đang ở case nào, nhưng về cơ chế lưu trữ thì khác.

• Nó vẫn đại diện cho ngữ nghĩa "HOẶC" giữa các type, nhưng bản chất của nó là một cái hộp chứa type cần "hoặc" ở bên trong.

Ví dụ, ta dùng Union declaration syntax:

// Union of existing types
public union Pet(Cat, Dog);

Được lowered thành:

[Union] public struct Pet : IUnion
{
    public Pet(Cat value) => Value = value;
    public Pet(Dog value) => Value = value;
    public object? Value { get; }
    ... // original body
}

Ta thấy rõ:

• Pet chỉ là một cái hộp, hoặc chứa Cat, hoặc chứa Dog
• Pet được gọi là union type
• Cat và Dog được gọi là case types

Compiler sẽ đảm bảo exhaustiveness khi dùng Union type với pattern matching.

💠 2. Hành vi (union behaviors)

💠 2.1. Union conversions

Có implicit conversion từ mỗi case type sang union type:

Pet pet = dog;
// becomes
Pet pet = new Pet(dog);

💠 2.2. Union matching

💠 2.2.1. Apply vào Value bên trong

• Khi kiểu dữ liệu của một value là union type tại compile time, thì pattern matching sẽ được áp dụng lên Value bên trong union type một cách ngầm định.

  Nghĩa là nó sẽ bị unwrap ngầm định thông qua .Value, rồi apply pattern lên Value đó (ngoại trừ trường hợp dùng var hoặc _).

Ví dụ:

Pet GetPet() => new Dog(...);

var description = GetPet() switch
{
    Dog dog => $"A dog: {dog.name}",
    Cat cat => $"A cat: {cat.name}",
    // No warning about non-exhaustive switch
};

Được lowered thành:

GetPet().Value switch {
    ...
}

Vì compiler biết Pet là một union type, nên nó sẽ biết switch expression ở trên đã được exhaustive rồi.

💠 2.2.2. Ngoại lệ var / _

Ngoại lệ là var hoặc _ pattern. Khi đó, pattern sẽ được apply vào chính Pet value, chứ không phải Value của Pet.

if (GetPet() is var pet) { ... } // 'pet' is the union value returned from `GetPet`

💠 2.2.3. Check null

Khi check 1 biến kiểu nullable union type là null hay không, thì việc check null không chỉ apply cho union type value, mà cả Value bên trong union type. (Điều này vẫn tuân thủ Union behavior ở trên - khi compile-time type là union type)

Pet? pet = ...;
pet is null

Được lowered thành:

Pet? pet = ...;

// Nếu Pet là class union type
pet == null || pet.Value == null

// Nếu Pet là struct union type
pet.HasValue == false || pet.GetValueOrDefault().Value == null

💠 2.2.4. Cạm bẫy

Pet pet = ...;
pet is Pet

Nó gần như luôn eval thành false, vì nó bị lowered thành:

pet.Value is Pet

Trong khi Value luôn là Dog hoặc Cat 😂.

💠 3. Một chỗ rất dễ gây nhầm lẫn: compile-time type đổi thì meaning cũng đổi

Nếu GetPet() trả về kiểu object, thì câu chuyện đổi hẳn.

object GetPet() => new Dog(...);

GetPet() is Pet;

• Khi đó, GetPet() is Pet sẽ eval thành true nếu GetPet() trả về một instance của Pet.

  • Lúc này, union behavior sẽ không được áp dụng, vì compile-time type của giá trị đầu vào là object, không phải Pet.
  • Do đó, GetPet() is Pet sẽ là true theo nghĩa check type bình thường ở runtime.

• Lý do là thiết kế hiện tại chỉ bật union matching khi compile-time type của giá trị đầu vào đã là union type. Ngoài trường hợp đó, union chỉ là một type bình thường / value bình thường, không có unwrap .Value ngầm.

• Đây là giải thích trực tiếp từ thảo luận của proposal: https://github.com/dotnet/csharplang/discussions/10040

💠 4. Mental model

Pet GetPet()      ->  GetPet() is Pet   // union semantics
object GetPet()   ->  GetPet() is Pet   // normal runtime type check

Tức là cùng một cú pháp is Pet, nhưng chỉ cần đổi compile-time type của biểu thức bên trái là meaning sẽ đổi theo.

Đây chính là lý do nhiều người chê proposal này "không idempotent" và dễ gây lú. Trong discussion https://github.com/dotnet/csharplang/discussions/10040 cũng nêu khá rõ rằng union pattern matching chỉ hoạt động khi compile-time type là union type.

💠 5. Tổng hợp — snippet dễ nhớ

// ✅ Union declaration syntax (C# 15 / .NET 11 Preview 2+)
public union Result<T>(T, Exception);

// ✅ Implicit conversion từ case type → union type
Result<int> ok    = 42;
Result<int> fail  = new Exception("oops");

// ✅ Pattern matching — exhaustive, không cần fallback
string msg = ok switch
{
    int value    => $"Success: {value}",
    Exception ex => $"Error: {ex.Message}",
    // No warning — compiler biết đã exhaustive
};

// ✅ null check unwrap cả hai tầng

// (union declaration → struct → Result<int>? is Nullable<Result<int>>)
Result<int>? maybe = ...;

// lowered: maybe.HasValue == false || maybe.GetValueOrDefault().Value == null
if (maybe is null) { }

// ⚠️ Cạm bẫy: luôn false vì bị unwrap ngầm
Result<int> r = ...;
r is Result<int>                                // → r.Value is Result<int> → false!

// ⚠️ Compile-time type quyết định behavior
Result<int>  r2 = ...;  r2 is int               // union semantics ✅
object       r3 = ...;  r3 is Result<int>       // runtime type check thường ⚠️

⚠️ Disclaimer — Preview feature

• Requires C# 15 / .NET 11 Preview 2 or later.
• As of .NET 11 Preview 2, UnionAttribute and IUnion are not yet included in the runtime. You must declare them manually in your project (see Union implementation in the docs).
• This is a preview — APIs and behaviors may change before the final release.

💠 1. What is a Union Type?

• A union type in C# is a union of types via a wrapper type.

• It is a type union — NOT a tagged union or discriminated union in the traditional sense. Quoted directly from the proposal:

  "The proposed unions in C# are unions of types and not 'discriminated' or 'tagged'."

  The distinction:

  • Discriminated union (F#, Haskell): uses a dedicated discriminator/tag field to tell cases apart.
  • Type union in C#: uses the runtime type of Value itself as the discriminator — no separate tag field.
  • In terms of behavior, it resembles a discriminated union in that pattern matching can identify the exact case, but the storage mechanism is different.

• It still expresses the "OR" semantics between types, but its underlying form is a box that holds one of the possible types.

For example, using the Union declaration syntax:

// Union of existing types
public union Pet(Cat, Dog);

Is lowered to:

[Union] public struct Pet : IUnion
{
    public Pet(Cat value) => Value = value;
    public Pet(Dog value) => Value = value;
    public object? Value { get; }
    ... // original body
}

Clearly:

• Pet is just a box that holds either a Cat or a Dog
• Pet is called the union type
• Cat and Dog are called case types

The compiler guarantees exhaustiveness when using a union type with pattern matching.

💠 2. Union Behaviors

💠 2.1. Union Conversions

There is an implicit conversion from each case type to the union type:

Pet pet = dog;
// becomes
Pet pet = new Pet(dog);

💠 2.2. Union Matching

💠 2.2.1. Applied to the Inner Value

• When the compile-time type of a value is a union type, pattern matching is implicitly applied to the Value inside the union type.

  In other words, the union is implicitly unwrapped via .Value, and the pattern is applied to that Value (except when using var or _).

Example:

Pet GetPet() => new Dog(...);

var description = GetPet() switch
{
    Dog dog => $"A dog: {dog.name}",
    Cat cat => $"A cat: {cat.name}",
    // No warning about non-exhaustive switch
};

Is lowered to:

GetPet().Value switch {
    ...
}

Because the compiler knows Pet is a union type, it knows the switch expression above is already exhaustive.

💠 2.2.2. Exception: var / _

The var or _ patterns are exceptions. In these cases, the pattern is applied to the Pet value itself, not its Value.

if (GetPet() is var pet) { ... } // 'pet' is the union value returned from `GetPet`

💠 2.2.3. Null Checking

When checking whether a nullable union type variable is null, the null check applies not only to the union value itself but also to the Value inside it. (This still follows the Union behavior above — when the compile-time type is a union type.)

Pet? pet = ...;
pet is null

Is lowered to:

Pet? pet = ...;

// If Pet is a class union type
pet == null || pet.Value == null

// If Pet is a struct union type
pet.HasValue == false || pet.GetValueOrDefault().Value == null

💠 2.2.4. The Trap

Pet pet = ...;
pet is Pet

This almost always evaluates to false, because it is lowered to:

pet.Value is Pet

While Value is always Dog or Cat 😂.

💠 3. A Common Source of Confusion: Changing the Compile-Time Type Changes the Meaning

If GetPet() returns object, the story changes entirely.

object GetPet() => new Dog(...);

GetPet() is Pet;

• Here, GetPet() is Pet evaluates to true if GetPet() returns an instance of Pet.

  • Union behavior is not applied, because the compile-time type of the input is object, not Pet.
  • Therefore, GetPet() is Pet is true in the sense of a normal runtime type check.

• The reason is that the current design only activates union matching when the compile-time type of the input is already a union type. Outside of that case, a union is just a regular type / regular value — no implicit .Value unwrapping.

• This is explained directly in the proposal discussion: https://github.com/dotnet/csharplang/discussions/10040

💠 4. Mental Model

Pet GetPet()      ->  GetPet() is Pet   // union semantics
object GetPet()   ->  GetPet() is Pet   // normal runtime type check

The same syntax is Pet, but simply changing the compile-time type of the left-hand expression changes the meaning entirely.

This is exactly why many people criticize this proposal as "not idempotent" and easy to get confused by. The discussion at https://github.com/dotnet/csharplang/discussions/10040 also makes it clear that union pattern matching only activates when the compile-time type is a union type.

💠 5. Summary — Quick Reference Snippet

// ✅ Union declaration syntax (C# 15 / .NET 11 Preview 2+)
public union Result<T>(T, Exception);

// ✅ Implicit conversion from case type → union type
Result<int> ok    = 42;
Result<int> fail  = new Exception("oops");

// ✅ Pattern matching — exhaustive, no fallback needed
string msg = ok switch
{
    int value    => $"Success: {value}",
    Exception ex => $"Error: {ex.Message}",
    // No warning — compiler knows all cases are covered
};

// ✅ Null check unwraps both layers
// (union declaration → struct → Result<int>? is Nullable<Result<int>>)
Result<int>? maybe = ...;
// lowered: maybe.HasValue == false || maybe.GetValueOrDefault().Value == null
if (maybe is null) { }

// ⚠️ Trap: always false due to implicit unwrapping
Result<int> r = ...;
r is Result<int>                            // → r.Value is Result<int> → false!

// ⚠️ Compile-time type determines behavior
Result<int>  r2 = ...;  r2 is int           // union semantics ✅
object       r3 = ...;  r3 is Result<int>   // normal runtime type check ⚠️

Source code: https://github.com/hoc081098/hoc081098/blob/master/notes/grouping_in_kotlin_vi_VN.kt

Đặt vấn đề

Giả sử chúng ta có một bài toán nhỏ như sau:

• Input: cho danh sách các sinh viên, mỗi sinh viên có các thuộc tính như sau

  • id: mã sinh viên.
  • name: tên sinh viên.
  • classId: mã lớp.
  • avgScore: điểm trung bình.

• Output: cho biết sinh viên có điểm trung bình cao nhất của mỗi lớp, kết quả được sắp xếp theo thứ tự tăng dần của mã lớp.

// Input: A list of Students, each Student has id, name, class_id, avg_score.
// Output: Map of class_id to the student with the highest avg_score in that class.
//         Keys should be sorted in ascending order.
// Example:
// Input: [
//   Student("1", "A", 1, 8.0),
//   Student("2", "B", 1, 9.0),
//   Student("3", "A", 2, 7.0),
// ]
// Output: {
//   1: Student("2", "B", 1, 9.0),
//   2: Student("3", "A", 2, 7.0),
// }

data class Student(
  val id: String,
  val name: String,
  val classId: Int,
  val avgScore: Double
)

@JvmField
val compareByAvgScore = compareBy<Student> { it.avgScore }

// (TreeMap take O(log n) time in the worst case to get/put).
typealias Output = SortedMap<Int, Student>

fun solution(students: List<Student>): Output = TODO()

fun main() {
  val students = listOf(
    Student("1", "A", 1, 8.0),
    Student("2", "B", 1, 9.0),
    Student("3", "A", 2, 7.0),
  )
  val output = mapOf(
    1 to Student("2", "B", 1, 9.0),
    2 to Student("3", "A", 2, 7.0),
  )
  check(solution(students) == output)
}

Solution 1: Sử dụng vòng lặp

Cách này ổn về mặt thời gian và không gian, nhưng cách viết khá dài dòng và khó đọc, và theo imperactive style (for loop + if statement).

// Time complexity (worst case) = n * (O(log n) + O(log n)) = O(2 * n * log n).
// Space: 1 TreeMap.
// ----
// Pros: good in terms of time complexity and space complexity.
// Cons: imperative style.
fun solution1(students: List<Student>): Output {
  val result = sortedMapOf<Int, Student>()
  for (student in students) {
    val current = result[student.classId]
    if (current == null || student.avgScore > current.avgScore) {
      result[student.classId] = student
    }
  }
  return result
}

Solution 2: Sử dụng groupBy và mapValues

Cách này sử dụng functional style, nhưng không tốt về mặt thời gian và không gian. Nó phải tạo ra 1 HashMap trung gian, và một TreeMap (SortedMap) để lưu kết quả. Ngoài ra, nó cũng phải duyệt 3 lần, 1 lần để groupBy, 1 lần để mapValues, trong mỗi lần mapValues lại phải duyệt để tìm max.

// Time complexity (worst case)
//     - groupByTo: O(n * ( O(1) + O(n) )) = O(n^2)
//     - mapValuesTo: O(n * ( O(log n) + O(n) )) = O(n^2 * log n)
//     - total: O(n^2 * log n)
// Space: 1 HashMap + 1 TreeMap
// ----
// Pros: functional style.
// Cons: bad in terms of time complexity and space complexity.
fun solution2(students: List<Student>): SortedMap<Int, Student> = students
  .groupByTo(hashMapOf()) { it.classId }
  .mapValuesTo(sortedMapOf()) { (_, v) -> v.maxBy { it.avgScore } }

Solution 3: Sử dụng groupingBy và reduce

// Time complexity (worst case)
//     - groupingBy: O(1) (just returns a Grouping object)
//     - reduceTo: O(n * ( O(log n) + O(log n) )) = O(n * log n)
//     - total: O(2 * n * log n)
// Space: 1 TreeMap (Grouping object is small).
// ----
// Pros: BEST. Functional style, good in terms of time complexity and space complexity.
// Cons: NO.
fun solution3(students: List<Student>): SortedMap<Int, Student> = students
  .groupingBy { it.classId }
  .reduceTo(sortedMapOf()) { _, accumulator, element -> maxOf(accumulator, element, compareByAvgScore) }

Cách này là tốt nhất cho đến hiện tại :), nó sử dụng functional style, và tốt về mặt thời gian và không gian.

• Bản chất, groupingBy sẽ tạo và return 1 object Grouping để lưu trữ Iterator và Key Selector để thực hiện việc reduce/aggregate sau đó.

  @SinceKotlin("1.1") public interface Grouping<T, out K> {
      fun sourceIterator(): Iterator<T>
      fun keyOf(element: T): K
  }
  

  Grouping không thực hiện việc duyệt, reduce/aggregate ngay lập tức, mà nó chỉ lữu trữ những cái cần thiết để thực hiện việc aggregate sau này. Đó là cơ chế LAZY, tương tự như Sequence của Koltin, Stream của Java, Observable của RxJava, Flow của Kotlin Coroutines, ...

• Sau đó, reduceTo sẽ duyệt qua Grouping object, và thực hiện việc reduce/aggregate trên từng Group xác định bởi Key Selector. Hàm reduceTo trên Grouping có cơ chế khá giống trên Iterable, nhưng nó không thực thi operation trên toàn bộ Iterable, mà nó thực thi operation trên từng Group xác định bởi Key Selector. Bản chất như sau (không giống source của stdlib 100%, vì lược bỏ những thứ không cần thiết):

inline fun <S, T : S, K, M : MutableMap<in K, S>> Grouping<T, K>.reduceTo(
  destination: M,
  operation: (key: K, accumulator: S, element: T) -> S
): M {
  for (element in sourceIterator()) {
    val key = keyOf(element)
    val accumulator = destination[key]
    destination[key] = if (accumulator == null && !destination.containsKey(key)) {
      element
    } else {
      operation(key, accumulator as S, element)
    }
  }
  return destination
}

Follow tôi, chúng tôi https://rx-mobile-team.github.io/profile/ để có thêm nhiều kiến thức về lập trình, không chỉ giới hạn ở Mobile (Android/iOS/Flutter) mà có cả Functional Programming, Reactive Programming, Data Structures, Algorithms, ... Những kiến thức chia sẻ ở đây, rất ít các Senior Dev và vân..vân.. chia sẻ cho các bạn đâu.

Do you have the same question as me 😇, when looking Jetpack Compose source code: Why do @Composable functions in Jetpack Compose usually use Dp.Unspecified as default value? Why not use null?

Dp.Unspecified is usually used as default value in Jetpack Compose source code

I. Dp class

I.1. Dp class declaration

At the moment, Dp class is defined as follows:

@Immutable
@kotlin.jvm.JvmInline
value class Dp(val value: Float) : Comparable<Dp> {
    @Stable
    inline operator fun plus(other: Dp): Dp = ...

    @Stable
    inline operator fun minus(other: Dp): Dp = ...

    // [...]
    // Other operators ...
    // [...]

    @Stable
    override /* TODO: inline */ operator fun compareTo(other: Dp) = value.compareTo(other.value)

    @Stable
    override fun toString() = if (isUnspecified) "Dp.Unspecified" else "$value.dp"

    companion object {
        @Stable
        val Hairline = Dp(value = 0f)

        @Stable
        val Infinity = Dp(value = Float.POSITIVE_INFINITY)

        /**
         * Constant that means unspecified Dp
         */
        @Stable
        val Unspecified = Dp(value = Float.NaN)
    }
}

Dp class is declared as inline value class wrapping a Float value. When compiling, the compiler will try to replace all Dp types with Float types (float in Java) as much as possible. This reduces memory usage and improves performance since heap allocation is eliminated, and Float type, a primitive type, is usually heavily optimized by the runtime. That is the optimization of Jetpack Compose.

The inline class spec is here.

I.2. Example ✍️

Let's create a simple example to see how the compiler optimizes Dp class, I create a @Composable fun MyComposable1 accepting a Dp as the first parameter.

MyComposable1 accepts a Dp as the first parameter

After compiling Kotlin and decompiling Java bytecode to Java code, we can see that the compiler has replaced Dp types with Float types.

Dp types are replaced with Float types

You may notice that the method name MyComposable1 has been changed, that is called mangling.

Mangling: since inline classes are compiled to their underlying type, it may lead to various obscure errors, for example unexpected platform signature clashes. To mitigate such issues, functions using inline classes are mangled by adding some stable hashcode to the function name.

II. Why do @Composable functions in Jetpack Compose usually use Dp.Unspecified as default value? Why not use null?

II.1. Why not use null?

After looking at the Dp class, we can understand why Dp is declared as inline value class, and the optimization of Jetpack Compose under the hood. Let's get back to the question at the beginning of this article.

Dp.Unspecified is usually used as default value in Jetpack Compose source code

Inline value class and Auto Boxing are keywords here.

"Boxing" refers to converting a primitive value into a corresponding wrapper object. Because this can happen automatically, it's known as autoboxing. Similarly, when a wrapper object is unwrapped into a primitive value then this is known as unboxing. (https://www.baeldung.com/java-wrapper-classes#autoboxing-and-unboxing)

If we use null as default value, we must declare the type as Dp? (nullable type). Since Dp? is a nullable type, compiler cannot use Float (aka float in Java) type to replace Dp? type. Instead, Dp? must be used!!!

nullable inline class types over primitive types are mapped to the boxed reference type (wrapper of an inline class)

Dp? is a reference type, not a primitive type, it requires heap allocation. Imagine we use Dp? types in many places (the worst case is in a loop or is in List/Row/Column/... UI), it will cause a lot of heap allocation, affect the application performance ⚠️, especially a UI application, its performance is very important to the user experience.

II.2. Demonstration example ✍️

Let's create a simple example using Dp? type, we create a @Composable fun MyComposable2 accepting a Dp? as the first parameter.

MyComposable2 accepts a Dp? as the first parameter

After decompiling, we can see that Dp type is not replaced with Float type, it is preserved. Inside UseMyComposable2, Dp.box-impl(Dp.constructor-impl((float)$this$dp$iv)) is used to box a Float value to a Dp. It is a heap allocation ⚠️.

Dp type is not replaced with Float type and heap allocation is used

That is the reason why we must not use null as default value. Dp.Unspecified is a better choice ✅, it wraps a Float.NaN value. Sometimes, we can use Dp.Hairline (aka 0.dp) as default value, depending on your use case.

II.3. Bonus ✅

• How about elvis operator ?:?
• How about == null?

Jetpack Compose has replacements, they are Dp.takeOrElse(block: () -> Dp): Dp and Dp.isUnspecified: Boolean. takeOrElse is an inline function, no lambda allocation, no heap allocation here 🥰.

Dp.takeOrElse and Dp.isUnspecified

Thanks for reading 🤗.

Follow me (@hoc081098) and us (https://rx-mobile-team.github.io/profile/) to have more knowledge about programming, not only limited to Mobile (Android/iOS/Flutter) but also Functional Programming, Reactive Programming, Data Structures, Algorithms, ...

Thay vì một function thuần: A -> C, Kleisli biểu diễn một function có context/effect: A -> M<C>.

Ví dụ với Continuation: Kleisli<Cont<R, *>, A, C> ≅ A -> Cont<R, C> trong đó Cont<R, A> ≅ (A -> R) -> R.

Nói tổng quát hơn thì Kleisli<M, A, B> ≅ A -> M<B>. Trong đó M là một type constructor đại diện cho effect/context, chẳng hạn như Option, Either<E, *>, IO, Cont<R, *>, etc.

2. 💠 Nếu M là một Monad, thì operation quan trọng nhất của Kleisli là andThen

andThen giúp compose các effectful arrows với nhau. Ở đây Kleisli<M, A, B> chỉ là notation/pseudocode để biểu diễn ý tưởng A -> M<B>. Trong các ngôn ngữ có HKT (Higher-Kinded Types) như Scala, ta có thể viết gần đúng là Kleisli[F[_], A, B]. Kotlin không có HKT thật, nên nếu implement thực tế cần dùng encoding riêng, wrapper riêng.

Signature

andThen: Kleisli<M, A, B> -> (Kleisli<M, B, C>) -> Kleisli<M, A, C>

có thể hiểu là:

andThen: (A -> M<B>) -> (B -> M<C>) -> (A -> M<C>)

Ví dụ bằng Kotlin-like pseudocode

// Kotlin-like pseudocode
Kleisli<M, A, B>.andThen(
    f: Kleisli<M, B, C>
): Kleisli<M, A, C>

Có thể được triển khai như sau:

// Kotlin-like pseudocode
fun Kleisli<M, A, B>.andThen(
    f: Kleisli<M, B, C>
): Kleisli<M, A, C> =
    Kleisli { a -> this.run(a).flatMap { b -> f.run(b) } }

Điểm mấu chốt nằm ở flatMap. Vì this.run(a) trả về một M<B>, nên ta không có ngay B để truyền tiếp vào f. Chính flatMap cho phép ta truyền một function B -> M<C> vào bên trong context M, để chain computation hiện tại M<B> với computation tiếp theo M<C> mà không cần unwrap B ra khỏi context một cách thủ công (và thường là không thể).

3. 💠 Trong Haskell, đây chính là Kleisli composition

(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> (a -> m c)
f >=> g = \a -> f a >>= g

• >>= là bind operator của Monad, hay còn gọi là flatMap trong các ngôn ngữ khác.
• \a -> f a >>= g là lambda expression với tham số a và biểu thức trả về là f a >>= g, nó tương đương với f(a).flatMap(g) trong các ngôn ngữ khác.

Vì >=> có hình dạng khá giống một con cá, nên các developers hay gọi vui >=> là Right Fish operator 🐟.

4. Kết lại

Function composition thông thường là: (.) :: (b -> c) -> (a -> b) -> (a -> c)

Chú ý thứ tự invoke functions từ phải sang trái.

Ví dụ: g . f bằng với \x -> g (f x), tức là chạy f trước rồi mới tới g.

Kleisli composition là phiên bản dành cho effectful functions: (>=>) :: (a -> m b) -> (b -> m c) -> (a -> m c)

Chú ý thứ tự invoke functions từ trái sang phải, giống như cách chúng ta đọc.

Ví dụ: f >=> g bằng với \x -> f x >>= g, tức là chạy f trước, rồi dùng bind/flatMap để chạy tiếp g.

Ngay tại thời điểm này, khi AI Agents đang được sử dụng rộng rãi trong Software Development, mình có cảm giác ngày càng ít người hứng thú với những thứ nằm phía sau framework, library hay API mà họ sử dụng hằng ngày. Nhiều người chỉ quan tâm tới việc ship feature nhanh nhất có thể, còn data structures, algorithms hay internal implementation dần bị xem là những chủ đề “không còn quá cần thiết nữa”.

Nhưng với mình thì ngược lại. Mình vẫn dùng AI mỗi ngày để nghiên cứu, review và hỗ trợ viết code, nhưng càng như vậy mình càng thấy hứng thú với việc đọc source code, tìm hiểu implementation và hiểu rõ trade-offs đằng sau những abstraction mà chúng ta sử dụng, và phần nào giúp cho cái công việc gen/review code của Agent bớt nhàm chán hơn.

Tạm nói qua bối cảnh như vậy, hôm trước mình dùng Agent để gen code thì nó gen ra một đoạn code dùng Kotlin ArrayDeque, mình đọc vào tất nhiên sẽ hiểu logic và semantics của nó rồi, vì mình đã xài ArrayDeque từ thời Java, và bắt đầu xài Kotlin ArrayDeque ngay từ khi nó được giới thiệu trong Kotlin 1.4.

Mình vẫn biết nó là “double-ended queue implementation backed by a resizable circular buffer”, tức là một hàng đợi hai đầu, cho phép thêm/xóa ở cả đầu trước và đầu sau. Nếu nhìn dưới góc độ amortized analysis, các thao tác thêm/xóa ở hai đầu là O(1). Nó có thể được dùng như là Stack (addLast/removeLast) hoặc Queue (addLast/removeFirst) tùy vào mục đích sử dụng.

Ngày xưa, mình hay dùng nó khi cần duyệt graph, ví dụ BFS với queue semantics (addLast/removeFirst) hoặc DFS với stack semantics (addLast/removeLast). Các bạn có thể xem PR https://github.com/InsertKoinIO/koin/pull/1801 - PR mình contribute vô Koin repository để refactor một hàm đệ quy sang DFS, hàm này flatten các Koin modules. Nhưng trước giờ mình cũng chỉ nhớ mang máng nó là resizable circular buffer chứ cũng không tìm hiểu rõ internal implementation của nó như nào. Hôm trước được dịp Agent gen code xong, thì mình cũng tranh thủ vô đọc Kotlin ArrayDeque luôn cho biết. Nên hôm nay, mình sẽ chia sẻ lại những gì mình đã tìm hiểu được về ArrayDeque implementation, hy vọng sẽ giúp các bạn có thêm kiến thức về một data structure rất hay và hữu ích này.

I. Internal state

@SinceKotlin("1.4")
public class ArrayDeque<E> : AbstractMutableList<E> {
  private var head: Int = 0
  private var elementData: Array<Any?>

  override var size: Int = 0
    private set
}

State cốt lõi của nó thực sự chỉ gồm:

• elementData: Array<Any?>: growable, nghĩa là khi cần thêm capacity thì nó sẽ được mở rộng lên. Đây chính là nơi lưu trữ data thực sự của ArrayDeque.
• head: index thực sự của phần tử head, nó là physical index trong elementData chứ không phải logical index (logical index của head luôn là 0).
• size: số phần tử hiện có trong ArrayDeque.

I.1. Physical vs Logical index

Trong ArrayDeque, có 2 khái niệm về index:

• Physical index: index thực sự trong elementData array. Ví dụ là head, nó có thể được dùng để truy cập phần tử head thực sự, cơ bản là elementData[head].

• Logical index: index mà phía bên ngoài nhìn vào. Đây là cái index mà developer chúng ta thường dùng để access element trong ArrayDeque. Ví dụ ArrayDeque.get(0) sẽ trả về phần tử head, ArrayDeque.get(size - 1) sẽ trả về phần tử cuối cùng.

I.2. Derived tail

Về mặt khái niệm, tail là physical index ngay sau phần tử cuối cùng (exclusive). Và tail có thể được derived dễ dàng từ head và size:

private fun positiveMod(index: Int): Int = if (index >= elementData.size) index - elementData.size else index

@kotlin.internal.InlineOnly
private inline fun internalIndex(index: Int): Int = positiveMod(head + index)

val tail = internalIndex(size)

internalIndex là method để convert logical index (0-based) sang physical index trong elementData. Logical index của head luôn là 0, tail thì có logical index là size. positiveMod là method để wrap-around qua 0 khi index vượt quá capacity của elementData.

Về mặt khái niệm có thể hiểu gần như modulo, nhưng implementation thực tế chỉ cần subtract một lần vì input đã nằm trong khoảng có thể wrap tối đa một vòng.

positiveMod(x) = x mod elementData.size
tail = (head + size) mod elementData.size

Tại sao không lưu tail như một field riêng biệt mà lại derived như vậy? Vì tail được derived như vậy để tiết kiệm 1 field, đồng thời đảm bảo invariant “tail = head + size” không thể bị drift (vì nó luôn được derived từ head và size).

I.3. Internal layout

Trong phần lớn thời gian, ArrayDeque sẽ ở một trong hai trạng thái:

• head nhỏ hơn tail (contiguous): các phần tử nằm liên tiếp trong elementData từ head đến tail-1.

[##, ##, e1, e2, e3, ##]
         ↑           ↑
        head        tail

• head lớn hơn tail (wrapped): sau khi tail vượt quá cuối array và vòng về 0, các phần tử sẽ nằm ở 2 đầu của elementData.

[e3, ##, ##, ##, e1, e2]
     ↑           ↑
    tail       head

Với 2 ví dụ trên thì nếu nhìn từ bên ngoài vào thì cả 2 đều có data giống nhau [e1, e2, e3].

II. Operations

Ta thử tìm hiểu 4 methods chính của ArrayDeque: addLast, addFirst, removeFirst, removeLast để xem head, tail và backing array thay đổi như thế nào khi add/remove ở hai đầu.

II.1. addLast

class ArrayDeque<E> : AbstractMutableList<E> {
  /**
   * Appends the specified [element] to this deque.
   */
  public fun addLast(element: E) {
    registerModification()
    ensureCapacity(size + 1)

    elementData[internalIndex(size)] = element
    size += 1
  }

  /**
   * Ensures that the capacity of this deque is at least equal to the specified [minCapacity].
   *
   * If the current capacity is less than the [minCapacity], a new backing storage is allocated with greater capacity.
   * Otherwise, this method takes no action and simply returns.
   */
  private fun ensureCapacity(minCapacity: Int) { ... }
}

• Đầu tiên, nó sẽ đảm bảo elementData.size >= size + 1 bằng cách gọi ensureCapacity, nghĩa là elementData có đủ chỗ trống để thêm 1 phần tử vào đuôi. Nếu capacity hiện tại không đủ thì sẽ được mở rộng lên (ta sẽ tìm hiểu việc mở rộng này ở phần sau).

• internalIndex(size) để lấy physical index của size (size chính là logical index của tail), sau đó gán element vào đó.

• Sau cùng tăng size lên 1, lúc này chỗ nào dùng tail thì cũng sẽ reflect value mới, vì tail được derived từ size và head.

Chỗ đặc biệt là internalIndex nó có cơ chế wrap-around qua 0 khi index vượt quá capacity của elementData, nên khi tail vượt quá cuối array thì nó sẽ tự động vòng về 0 để tiếp tục add phần tử vào đầu array. Đây chính là circular buffer semantics. Lấy ví dụ:

[##, ##, e1, e2, e3]
         ↑
        head
# size = 3, head = 2, tail = 0, capacity = 5

-------- addLast(e4) --------

[e4, ##, e1, e2, e3]
     ↑   ↑
    tail head
# size = 4, head = 2, tail = 1, capacity = 5

II.2. addFirst

class ArrayDeque<E> : AbstractMutableList<E> {
  private fun decremented(index: Int): Int = if (index == 0) elementData.lastIndex else index - 1

  /**
   * Prepends the specified [element] to this deque.
   */
  public fun addFirst(element: E) {
    registerModification()
    ensureCapacity(size + 1)

    head = decremented(head)
    elementData[head] = element
    size += 1
  }
}

• Tương tự như addLast, nó cũng sẽ đảm bảo capacity đủ để thêm phần tử mới.

• Cái hay ở chỗ là head bây giờ phải lùi về trước, thông qua head = decremented(head). Ta có thể hiểu theo kiểu logical index là head = head-1, nhưng vì head là physical index nên nó phải được decrement với wrap-around qua 0, nghĩa là nếu head đang ở 0 thì nó sẽ lùi về cuối array (elementData.lastIndex). Ta thấy nó đi theo chiều ngược lại so với addLast, nhưng vẫn đảm bảo được circular buffer semantics.

• Gán element vào elementData[head] sau khi đã lùi head về trước, rồi tăng size lên 1.

Lấy ví dụ circular buffer semantics, khi head đã ở vị trí 0 và ta addFirst thêm 1 phần tử nữa thì head sẽ lùi về cuối array:

[e1, e2, e3, ##, ##]
 ↑
head
# size = 3, head = 0, tail = 3, capacity = 5

-------- addFirst(e0) --------

[e1, e2, e3, ##, e0]
             ↑   ↑
            tail head
# size = 4, head = 4, tail = 3, capacity = 5

II.3. removeFirst

class ArrayDeque<E> : AbstractMutableList<E> {
  private fun incremented(index: Int): Int = if (index == elementData.lastIndex) 0 else index + 1

  /**
   * Removes the first element from this deque and returns that removed element, or throws [NoSuchElementException] if this deque is empty.
   */
  @IgnorableReturnValue
  public fun removeFirst(): E {
    if (isEmpty()) throw NoSuchElementException("ArrayDeque is empty.")
    registerModification()

    val element = internalGet(head)
    elementData[head] = null
    head = incremented(head)
    size -= 1
    return element
  }
}

• Đầu tiên, nó sẽ check nếu ArrayDeque đang rỗng thì sẽ throw NoSuchElementException.

• Tiếp theo, lấy phần tử head thực sự thông qua internalGet(head) (để return cho caller). Sau đó, gán null vào vị trí head trong elementData để clear reference (để GC có thể thu hồi nếu cần).

• Tiếp đến, quan trọng nhất, đó chính là việc đẩy head về sau một vị trí, hiểu theo nghĩa logical index là head = head + 1. Tương tự như addFirst có decremented, thì removeFirst có incremented để +1 nhưng wrap-around. incremented chính là dual của decremented, cũng có cơ chế wrap-around qua 0 nếu head đang ở cuối array.

• Tiếp theo, giảm size đi 1 để reflect việc đã remove 1 phần tử.

• Sau cùng, đơn giản chỉ return phần tử đã remove.

Ta lấy ví dụ head ở cuối array và ta thực hiện removeFirst thì head sẽ wrap về đầu array:

[e1, e2, ##, ##, e0]
         ↑       ↑
        tail    head
# size = 3, head = 4, tail = 2, capacity = 5

-------- removeFirst() --------

[e1, e2, ##, ##, ##]
 ↑       ↑
head    tail
# size = 2, head = 0, tail = 2, capacity = 5

II.4. removeLast

class ArrayDeque<E> : AbstractMutableList<E> {
  /**
   * Removes the last element from this deque and returns that removed element, or throws [NoSuchElementException] if this deque is empty.
   */
  @IgnorableReturnValue
  public fun removeLast(): E {
    if (isEmpty()) throw NoSuchElementException("ArrayDeque is empty.")
    registerModification()

    val internalLastIndex = internalIndex(lastIndex)
    val element = internalGet(internalLastIndex)
    elementData[internalLastIndex] = null
    size -= 1
    return element
  }
}

• Tương tự như removeFirst, nó sẽ check nếu ArrayDeque đang rỗng thì sẽ throw NoSuchElementException.

• Lấy physical index của phần tử cuối lastIndex - logical index, thông qua internalLastIndex = internalIndex(lastIndex). Sau đó, lấy phần tử cuối thực sự thông qua element = internalGet(internalLastIndex) (để return cho caller).

• Gán null vào internalLastIndex trong elementData để clear reference (để GC có thể thu hồi nếu cần).

• Giảm size đi 1 để reflect việc đã remove 1 phần tử.

• Sau cùng, đơn giản chỉ return phần tử đã remove.

Ta thử lấy ví dụ phần tử cuối ở đầu array và ta thực hiện removeLast:

[e1, ##, ##, ##, e0]
     ↑           ↑
    tail        head
# size = 2, head = 4, tail = 1, capacity = 5

-------- removeLast() --------

[##, ##, ##, ##, e0]
 ↑               ↑
tail            head
# size = 1, head = 4, tail = 0, capacity = 5

III. Capacity expansion

III.1. ensureCapacity và copyElements

Method ensureCapacity sẽ đảm nhận nhiệm vụ mở rộng capacity của elementData khi cần thiết, cụ thể là khi addFirst hoặc addLast được gọi mà size + 1 > elementData.size (tức là capacity hiện tại không đủ để chứa phần tử mới).

class ArrayDeque<E> : AbstractMutableList<E> {
  /**
   * Constructs an empty deque with specified [initialCapacity], or throws [IllegalArgumentException] if [initialCapacity] is negative.
   */
  public constructor(initialCapacity: Int) {
    elementData = when {
      initialCapacity == 0 -> emptyElementData
      initialCapacity > 0 -> arrayOfNulls(initialCapacity)
      else -> throw IllegalArgumentException("Illegal Capacity: $initialCapacity")
    }
  }

  /**
   * Constructs an empty deque.
   */
  public constructor() {
    elementData = emptyElementData
  }

  /**
   * Ensures that the capacity of this deque is at least equal to the specified [minCapacity].
   *
   * If the current capacity is less than the [minCapacity], a new backing storage is allocated with greater capacity.
   * Otherwise, this method takes no action and simply returns.
   */
  private fun ensureCapacity(minCapacity: Int) {
    if (minCapacity < 0) throw IllegalStateException("Deque is too big.")    // overflow
    if (minCapacity <= elementData.size) return
    if (elementData === emptyElementData) {
      elementData = arrayOfNulls(minCapacity.coerceAtLeast(defaultMinCapacity))
      return
    }

    // fun newCapacity(oldCapacity: Int, minCapacity: Int): Int
    val newCapacity = AbstractList.newCapacity(elementData.size, minCapacity)
    copyElements(newCapacity)
  }

  /**
   * Creates a new array with the specified [newCapacity] size and copies elements in the [elementData] array to it.
   */
  private fun copyElements(newCapacity: Int) {
    val newElements = arrayOfNulls<Any?>(newCapacity)
    // fun Array<out T>.copyInto(destination: Array<T>, destinationOffset: Int = 0, startIndex: Int = 0, endIndex: Int = size): Array<T>
    elementData.copyInto(newElements, 0, head, elementData.size)
    elementData.copyInto(newElements, elementData.size - head, 0, head)
    head = 0
    elementData = newElements
  }

  internal companion object {
    private val emptyElementData = emptyArray<Any?>()
    private const val defaultMinCapacity = 10
  }
}

• Nếu minCapacity < 0 tức là minCapacity đã vượt quá biên trên Int.MAX_VALUE nên value nó bị thành âm (overflow), lúc này sẽ throw IllegalStateException với message "Deque is too big.".

• Nếu minCapacity <= elementData.size tức là capacity hiện tại đã đủ lớn để chứa phần tử mới, thì method sẽ không làm gì cả và return luôn.

• Nếu elementData === emptyElementData — ở đây emptyElementData là một sentinel value dùng để biểu diễn trạng thái backing storage chưa được allocate thực sự, thường xảy ra khi ArrayDeque được tạo bằng constructor() rỗng — thì sẽ tạo một array mới với capacity là max(minCapacity, defaultMinCapacity = 10), tức là ít nhất 10 phần tử trong lần cấp phát đầu tiên.

• Trường hợp cuối cùng, ta phải alloc một array mới với newCapacity = AbstractList.newCapacity thông qua copyElements. Method copyElements có nhiệm vụ alloc một array với length = newCapacity, sau đó copy phần tử từ elementData sang newElements theo nguyên tắc sau:

  • đầu tiên là các items từ head đến elementData.size - 1
  • rồi tiếp theo là các items từ 0 đến head - 1. Sau khi copy xong thì head sẽ được reset về 0, và elementData sẽ trỏ sang array mới newElements.

Điểm nổi bật là sau khi ta “rải” các items từ array cũ sang newElements thì layout của ArrayDeque sẽ được reset về contiguous layout, nghĩa là head sẽ ở vị trí 0 và tail sẽ ở vị trí size, điều này giúp cho trạng thái buffer sạch hơn.

Resize không chỉ tăng capacity, mà còn “duỗi thẳng” circular layout về lại linear layout.

III.2. Tại sao lại tăng capacity lên 1.5x?

Ta thử tìm hiểu tiếp xem new capacity được tính như nào thông qua AbstractList.newCapacity:

public abstract class AbstractList<out E> protected constructor() : AbstractCollection<E>(), List<E> {
  internal companion object {
    /** [oldCapacity] and [minCapacity] must be non-negative. */
    internal fun newCapacity(oldCapacity: Int, minCapacity: Int): Int {
      // overflow-conscious
      var newCapacity = oldCapacity + (oldCapacity shr 1)
      if (newCapacity - minCapacity < 0)
        newCapacity = minCapacity
      if (newCapacity - maxArraySize > 0)
        newCapacity = if (minCapacity > maxArraySize) Int.MAX_VALUE else maxArraySize
      return newCapacity
    }
  }
}

Ta focus vào dòng var newCapacity = oldCapacity + (oldCapacity shr 1), ở đây có thể hiểu là newCapacity = oldCapacity + oldCapacity/2 (sử dụng “shift right” để chia cho 2), nên newCapacity = oldCapacity * 1.5. Đây là một chiến lược phổ biến để tăng capacity của các data structure dạng array, vì nó giúp cân bằng giữa việc giảm số lần mở rộng (vì mỗi lần mở rộng sẽ tăng capacity lên 50%) và tránh lãng phí quá nhiều memory (so với việc tăng gấp đôi capacity).

Câu hỏi đặt ra là: “Tại sao không sử dụng 2x mà lại là 1.5x”? 2x, thường thấy trong std::vector của trình biên dịch GCC - C++, sẽ đỡ phải copy nhiều hơn, nhưng nó cũng sẽ lãng phí nhiều memory hơn, đặc biệt là khi oldCapacity đã lớn, có thể lãng phí đến gần 50% bộ nhớ ở lần cấp phát cuối cùng.

Còn 1.5x (dùng trong Java ArrayList, Kotlin ArrayDeque, hoặc std::vector của MSVC) là “điểm ngọt” (sweet spot), không lãng phí quá nhiều memory, giữ cho lượng RAM lãng phí ở mức tối đa chỉ khoảng 33%, nhưng ta chấp nhận phải copy nhiều hơn một chút. Đây chính là một trade-off giữa performance và memory efficiency.

Hơn nữa, về mặt lý thuyết, việc chọn hệ số 1.5x thay vì 2x cũng có thể giúp tăng khả năng tái sử dụng bộ nhớ trong một số mô hình cấp phát. Vấn đề này có thể được chứng minh qua toán học khi xét ở lần cấp phát thứ n:

• Trường hợp dùng 2x: Size của mảng mới cần cấp phát là 2^n. Tuy nhiên, con số này luôn lớn hơn 1 đơn vị so với tổng size của tất cả các mảng cũ đã bị vứt bỏ trước đó (sum(2^i, i=0..n-1) = 2^n - 1). Điều này làm giảm khả năng tái sử dụng trực tiếp các vùng nhớ cũ theo mô hình lý thuyết.

• Trường hợp dùng 1.5x: Size của mảng mới là 1.5^n. Khác với hệ số 2, từ lần cấp phát thứ 2 trở đi, kích thước này sẽ nhỏ hơn tổng size của bộ nhớ cũ đã giải phóng (sum(1.5^i, i=0..n-1)). Nhờ vậy, về mặt lý thuyết Memory Allocator có nhiều cơ hội hơn để tái sử dụng các vùng nhớ đã được giải phóng.

Tất nhiên, trong thực tế chuyện allocator có tái sử dụng được vùng nhớ cũ hay không còn phụ thuộc vào runtime, GC, allocator và platform cụ thể. Vì vậy, nên xem đây là một intuition về trade-off, không phải một guarantee tuyệt đối.

IV. Complexity Analysis

IV.1. Get operations

Vì ArrayDeque vẫn map logical index sang physical index bằng internalIndex(index), nên get(index) vẫn là O(1).

Tuy nhiên, các thao tác insert/remove ở giữa deque không còn O(1), vì lúc đó phải dịch chuyển elements ở một phía để giữ layout hợp lệ.

IV.2. Remove first/last operations

Các method remove phần tử như removeFirst và removeLast đều có complexity là O(1), vì chúng chỉ clear slot tương ứng, cập nhật head/size, và không cần loop hay copy elements.

IV.3. Add first/last operations

Các method add phần tử như addFirst và addLast có complexity amortized O(1).

Trong phần lớn trường hợp, chúng chỉ cần ghi phần tử vào vị trí tương ứng trong backing array rồi cập nhật head/size. Rõ ràng, đây chính là O(1) cho mỗi lần insert.

Tuy nhiên, khi capacity không đủ, ArrayDeque phải allocate array mới và copy toàn bộ elements sang array mới, lúc này chi phí là O(N). Dù vậy, vì mỗi lần mở rộng capacity tăng theo hệ số cố định khoảng 1.5x, resize không xảy ra ở mọi lần insert mà chỉ diễn ra khi capacity hiện tại đã đầy.

Tổng chi phí copy qua N lần insert tạo thành một chuỗi hình học và vẫn bị chặn bởi O(N). Cụ thể, giả sử capacity bắt đầu là c và mỗi lần resize tăng theo hệ số r = 1.5, thì các lần resize sẽ phải copy số phần tử xấp xỉ:

c + cr + cr² + cr³ + ... + crᵏ

Đây là một chuỗi hình học - là dãy số mà mỗi số sau bằng số trước nhân với một hằng số.

Sau lần resize cuối, capacity crᵏ vừa đủ để chứa N phần tử nên chắc chắn N <= crᵏ. Nhưng nó cũng không thể quá lớn hơn N nhiều, vì trước lần resize đó, capacity cũ là crᵏ⁻¹ và capacity cũ chưa đủ chứa N, nên crᵏ⁻¹ < N tương đương crᵏ < rN. Do đó, ta suy ra số hạng cuối crᵏ cũng cùng bậc với N:

N <= crᵏ < rN

Dựa theo công thức tính tổng cấp số nhân, vì r > 1 là hằng số, nên tổng của chuỗi hình học luôn cùng bậc với số hạng lớn nhất:

c + cr + cr² + ... + crᵏ
 = c(rᵏ⁺¹ - 1) / (r - 1)
 = O(crᵏ)
 = O(N)

Nói cách khác, dù một vài lần insert phải trả giá đắt vì resize/copy, tổng chi phí copy sau N lần insert vẫn chỉ tăng tuyến tính theo N. Vì vậy, khi chia đều chi phí đó cho N lần insert, mỗi lần insert có chi phí trung bình là amortized O(1).

V. Takeaways

• ArrayDeque được implement bằng resizable circular buffer.

  • Chỉ cần 3 state chính: elementData, head và size.
  • tail không được lưu trữ mà được derived từ head và size.
  • Capacity tăng khoảng 1.5x để cân bằng giữa performance và memory efficiency.
  • Khi resize, layout sẽ được normalize về contiguous form với head = 0.

• removeFirst và removeLast là O(1).

• addFirst và addLast là amortized O(1).

Nói ngắn gọn: ArrayDeque nhanh không phải vì nó “ma thuật”, mà vì nó né được việc shift elements bằng cách xoay index thay vì xoay data.

Internet
   ↓
Nginx (IP flood protection)
   ↓
YARP (user / tenant policy limit)
   ↓
Service (domain limit / concurrency limit)

1. Nginx - tầng hạ tầng (edge / infra level)

• Config các basic rate limiting nhằm mục đích chống spam/DDoS, chống flood thô. Đây là lớp phòng thủ đầu tiên trước khi request chạm tới business logic. Nó không hiểu JWT là gì, không biết UserId hay TenantId nào đang gọi. Nó chỉ nhìn thấy network-level metadata.
• Ví dụ: limit theo IP address, Geo block (theo quốc gia/vùng), hoặc giới hạn request rate và connection ở mức IP
• Mục tiêu: network-level protection - chặn rác ở tầng infra/network, trước khi đi sâu vào business logic

http {
    # ... other http settings ...
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=5r/s;
}

server {
    # ... other server settings ...

    limit_req_status 429; # Return "429 Too Many Requests" error
    location /login/ {
        limit_req zone=mylimit burst=10 nodelay;
        # ... other location settings, e.g., proxy_pass ...
    }
}

• Sử dụng limit_req_zone directive trong http block với

  • $binary_remote_addr: sử dụng IP address của client trong dạng nhị phân để làm KEY.
  • zone=mylimit:10m: tạo 1 zone tên là "mylimit" có size 10MB memory (có thể lưu trữ trạng thái của khoảng 160,000 địa chỉ IP)
  • rate=5r/s: giới hạn tốc độ là 5 requests/giây cho mỗi IP address.

• Sử dụng limit_req directive trong location block để áp dụng limit đã định nghĩa ở trên.

  • zone=mylimit: chỉ định zone đã tạo ở trên
  • burst=10: Thiết lập một "hàng đợi" dự phòng cho phép tối đa 10 request vượt định mức. Thay vì bị từ chối ngay lập tức khi vượt quá rate, các request này sẽ được tạm giữ lại trong bộ nhớ của Nginx.
  • Mặc định (không có nodelay): Nginx sẽ "điều tiết" lưu lượng bằng cách áp đặt độ trễ (delay). Các request trong hàng đợi burst sẽ bị ép phải xếp hàng và đi qua cửa kiểm soát từng cái một theo đúng nhịp độ của rate. Kết quả là người dùng sẽ thấy ứng dụng bị chậm lại (latency cao) nhưng không bị lỗi. nodelay: Khi kích hoạt, Nginx sẽ ưu tiên trải nghiệm người dùng bằng cách cho phép các request trong hàng đợi được xử lý ngay lập tức mà không cần chờ đợi. Tuy nhiên, mỗi request "đi tắt" này vẫn sẽ chiếm dụng một slot trong hàng đợi burst và chỉ được giải phóng (hồi slot) theo đúng tốc độ của rate.
  • Lưu ý: Chỉ khi hàng đợi dự phòng này bị lấp đầy hoàn toàn (vượt quá cả rate lẫn burst), Nginx mới bắt đầu từ chối bằng status code đã cấu hình (ví dụ: 429).

2. API Gateway (ví dụ YARP)

• Config rate limiting chung cho các services phía sau. Tầng này có thể parse và hiểu JWT, UserId, TenantId, API key, API version. Khác với Nginx, gateway hiểu "ai đang gọi", không chỉ "IP nào đang gọi". Vì vậy, nó phù hợp để enforce các chính sách truy cập và quota mang tính hệ thống.
• Ví dụ: limit theo UserId, TenantId, apply quota theo API key, API version, Quota theo app.
• Mục tiêu: policy-level control - bảo vệ tài nguyên theo các rules/policies chung cho nhiều services.

3. Service: tầng business logic cụ thể

• Khi request đi tới service, rate limiting không còn đơn thuần là bảo vệ hạ tầng hay thực thi policy chung nữa, mà gắn trực tiếp với domain. Ở đây, ta config rate limiting riêng cho service đó, dựa trên business logic đặc thù của service.
• Ví dụ: một user chỉ được tạo 5 order/phút, một tenant chỉ được gửi 1,000 webhook/phút, chỉ cho phép 10 concurrent job xử lý
• Mục tiêu: business-level control - bảo vệ tài nguyên dựa trên logic cụ thể.

4. Rate Limiting Algorithms trong ASP.NET Core (có thể dùng cho YARP và Services)

• Fixed Window: Đơn giản, giới hạn số requests trong 1 window cố định. Nhưng dễ bị spike ở window boundary.
• Sliding Window: Cải tiến hơn Fixed Window. Giới hạn N request/X giây gần nhất bằng cách chia Window thành nhiều segment cố định, mỗi khi check sẽ đếm số request của segment hiện tại với các segment trước đó. Giảm spike tại window boundary. Nhưng tốn kém hơn về mặt memory vì phải lưu nhiều segment. Đọc thêm tại bài viết trên Facebook
• Token Bucket: Mỗi request sẽ "rút" token từ bucket. Bucket được refill theo thời gian. Cho phép burst trong 1 thời gian ngắn & giữ tốc độ trung bình trong thời gian dài. Phù hợp với các hệ thống cần cho phép burst nhưng vẫn kiểm soát lưu lượng trung bình. Đọc thêm tại bài viết trên Facebook
• Concurrency: Giới hạn số requests đang được xử lý đồng thời tại 1 thời điểm. Không giới hạn số request theo thời gian, mà giới hạn số request đang xử lý đồng thời. Phù hợp với các hệ thống có tài nguyên hạn chế hoặc cần đảm bảo hiệu suất ổn định.

Một đoạn code ví dụ về cách cấu hình Rate Limiting trong YARP:

File Program.cs

// 1. Add Rate Limiter.
services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("customPolicy", opt =>
    {
        opt.PermitLimit = 4;
        opt.Window = TimeSpan.FromSeconds(12);
        opt.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        opt.QueueLimit = 2;
    });
});

// 2. add the RateLimiter middleware.
app.UseRateLimiter();

app.MapReverseProxy();

File appsettings.json - Apply customPolicy rate limit policy cho route1:

{
  "ReverseProxy": {
    "Routes": {
      "route1" : {
        "ClusterId": "cluster1",
        "RateLimiterPolicy": "customPolicy",
        "Match": {"Hosts": [ "localhost" ]}
      }
    },
    "Clusters": {
      "cluster1": {
        "Destinations": {
          "cluster1/destination1": {
            "Address": "https://localhost:10001/"
          }
        }
      }
    }
  }
}

Đọc thêm Microsoft docs: Rate Limiting in YARP

Khi phân tầng đúng, chúng bổ trợ nhau

• Edge (Nginx): stateless & IP-based -> chống rác ở network level
• Gateway (YARP): identity-aware -> enforce policy theo identity
• Service: stateful & domain-aware -> enforce invariant theo domain

Chúng chỉ overlap khi ranh giới không rõ ràng. Ví dụ, nếu Nginx limit quá chặt, request hợp lệ có thể bị chặn trước khi tới gateway hoặc service, khiến các tầng phía dưới không còn ý nghĩa thực tế. Hoặc nếu cùng một logic rate limiting bị định nghĩa trùng nhau ở cả Nginx và Gateway, hệ thống sẽ trở nên rối rắm và khó kiểm soát. Rate limiting, nếu nhìn đúng bản chất, không phải một cấu hình duy nhất. Nó là một chiến lược phân tầng. Và sự rõ ràng trong phân tầng mới là thứ quyết định hệ thống có gọn gàng hay trở thành spaghetti policy.

Observable trong ReactiveX phải thuân thủ quy tắc Serially, tức là phải đảm bảo các sự kiện phát ra không được overlap lên nhau. Quy tắc này không bắt buộc các event (signal) phải được delivered đến các subscriber ở cùng một thread. Nó vẫn có thể được delivered đến các subscriber ở các thread khác nhau, nhưng nó phải đảm bảo các event không được overlap lên nhau (tức phải đồng bộ thông qua các cơ chế như lock, atomic, ...).

Ví dụ: một Observable phát ra onNext(1), onNext(2), onNext(3) thì 1 subscriber có thể nhận onNext(1) ở thread A, onNext(2) ở thread B, onNext(3) ở thread A, nhưng nó không được phép nhận onNext(2) trong khi onNext(1) đang được delivered.

Hãy xem Reactive Streams Specification for the JVM để thấy rõ hơn.

II. Subjects are not thread-safe on the Observer side 🥺

Subject không phải là thread-safe ở phía Observer. Nếu chúng ta invoke onNext, onError, onCompleted trên Subject từ nhiều thread khác nhau thì có thể dẫn đến các event bị overlap lên nhau, và điều này sẽ làm Subject không đảm bảo quy tắc Serially nữa.

Trong RxJava, tất cả Subject đều không thread-safe, ngoại trừ SerializedSubject. Chỉ cần gọi toSerialized() trên 1 Subject bất kì là chúng ta đã có được một SerializedSubject. SerializedSubject sẽ serialize các lời gọi tới method của Observer side, điều này được đảm bảo bằng 1 queue có type AppendOnlyLinkedArrayList được synchronized bởi chính SerializedSubject đó, queue này sẽ giữ các event (signal/notification) bị missed, để sau đó sẽ loop và deliver chúng đến các Observer một cách synchronized.

1. ⚠️ Synchronization anomaly was detected

Trong RxSwift, 4 loại Subject PublishSubject, BehaviorSubject, ReplaySubject, AsyncSubject đều không thread-safe.

✍️ Hãy lấy ví dụ với PublishSubject, gọi onNext trên PublishSubject từ nhiều thread khác nhau cùng lúc.

❌ Lỗi này xảy ra khi event thứ nhất onNext(1) được send từ thread của queue-1, onNext(2) event sau lại được send từ thread của queue-2 trong khi event 1 đang được delivered,tức vẫn chưa hoàn thành việc delivery event 1.

🧐 RxSwift detect được chúng ta đang gọi từ nhiều thread khác nhau, sẽ log ra lỗi ⚠️ Synchronization anomaly was detected. Nếu chúng ta enable flag FATAL_SYNCHRONIZATION, thì RxSwift sẽ crash app thông qua fatalError.

✅ Cách fix đơn giản nhất là tạo một Serial DispatchQueue, và đưa các lời gọi tới PublishSubject vào trong DispatchQueue đó. Hoặc sử dụng một NsRecursiveLock để đảm bảo các lời gọi tới Observer side của PublishSubject được synchronized.

Serial DispatchQueue

NsRecursiveLock

2. ⚠️ Reentrancy anomaly was detected

Nếu chúng ta đảm bảo các lời gọi tới Observer side một Subject luôn trên cùng một Thread, nhưng vẫn có thể gặp lỗi ⚠️ Reentrancy anomaly was detected. Lỗi này hay gặp khi chúng ta gọi các Observer side của một Subject, bên trong chính Observer của Subject.

✍️ Hãy lấy ví dụ gọi onCompleted bên trong onNext closure.

❌ Lỗi này xảu ra khi onNext(2) đang được delivered, và onCompleted được gọi trong khi đang trong quá trình delivery event 2.

🧐 Tương tự như Synchronization anomaly, RxSwift sẽ detect được chúng ta đang gọi 1 method của Observer side bên trong chính Observer của Subject, và sẽ log ra lỗi ⚠️ Reentrancy anomaly was detected (hoặc crash nếu chúng ta enable flag FATAL_REENTRANCY thông qua fatalError).

✅ Cách fix đơn giản nhất là tránh gọi các method của Observer side bên trong chính Observer của Subject. Hãy sử dụng các filtering operators như filter, take, skip, distinctUntilChanged, takeWhile, takeUntil, ... để filter các event không mong muốn. Hãy reactive thay vì imperative.

They [Subjects] are the "mutable variables" of the Rx world and in most cases you do not need them. Typically a solution with Create or the other operators allows you to just wire up continuations without adding extra state. Stated slightly differently, it is good practice to minimize the number of objects that hold on to subscribers, you just want to pass them through. (Erik Meijer - Rx.Net inventor).

3. Tìm hiểu cách RxSwift detect các lỗi trên

Đầu tiên, hãy xem source của PublishSubject.swift. PublishSubject conforms ObserverType protocol, ObserverType có một số extension onNext, onError, onCompleted forward tới on(_ event: Event<Int>).

Hãy xem implementation của on(_ event: Event<Int>) trong PublishSubject.swift. Khi flag DEBUG được enable, RxSwift sẽ dùng SynchronizationTracker để track lúc bắt đầu việc dispatch event (dòng code self.synchronizationTracker.register(synchronizationErrorMessage: .default)) và track lúc kết thúc (dòng code defer { self.synchronizationTracker.unregister() }).

SynchronizationTracker chứa một Dictionary var threads = [UnsafeMutableRawPointer: Int]() với key là con trỏ tới Thread, value là số lượng lời gọi on(_ event: Event<Int>) đang được thực thi (in-progress) trên Thread tương ứng.

Bên trong register, chúng ta sẽ tăng value lên 1 cho key là con trỏ tới Thread hiện tại. Nếu count > 1, tức là có nhiều hơn 1 lời gọi on(_ event: Event<Int>) đang được thực thi (in-progress) trên Thread hiện tại, và đang bị overlap lên nhau (Reentrancy anomaly). Lúc đó, RxSwift sẽ log ra lỗi ⚠️ Reentrancy anomaly was detected hoặc crash.

Sau đó, check số lượng Threads đang trong trạng thái delivering. Nếu số lượng threads đang thực thi việc delivery event lớn hơn một, tức là có nhiều hơn 1 Thread đang delivery event đồng thời (Synchronization anomaly). Lúc đó, RxSwift sẽ log ra lỗi ⚠️ Synchronization anomaly was detected hoặc crash.

Cuối cùng, sau khi delivery event, hàm unregister được gọi để giảm số lượng value đi 1 cho key là con trỏ tới Thread hiện tại. Nếu value về 0, tức là không còn lời gọi on(_ event: Event<Int>) nào đang được thực thi trên Thread hiện tại, chúng ta sẽ remove key đó ra khỏi Dictionary threads.

Logic đơn giản như vậy thôi 🥰🥰. Các bạn có thể tìm hiểu thêm trong source code của RxSwift Rx.swift và PublishSubject.swift.

Follow tôi, chúng tôi https://rx-mobile-team.github.io/profile/ để có thêm nhiều kiến thức về lập trình, không chỉ giới hạn ở Mobile (Android/iOS/Flutter) mà có cả Functional Programming, Reactive Programming, Data Structures, Algorithms, ... Những kiến thức chia sẻ ở đây, rất ít các Senior Dev và vân..vân.. chia sẻ cho các bạn đâu.