feat: introduce opt-in annotation preventing the erroneous usage of A…

…PI intended to be internal
Collektive · Feb 20, 2025 · 1940aba · 1940aba
1 parent 0babc68
commit 1940aba
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 2 deletions.
diff --git a/dsl/src/commonMain/kotlin/it/unibo/collektive/aggregate/api/Aggregate.kt b/dsl/src/commonMain/kotlin/it/unibo/collektive/aggregate/api/Aggregate.kt
@@ -8,6 +8,15 @@ import kotlinx.serialization.serializer
 
 typealias YieldingScope<Initial, Return> = YieldingContext<Initial, Return>.(Initial) -> YieldingResult<Initial, Return>
 
+/**
+ * Represents methods intended to be used internally only.
+ * The usage of these methods is discouraged and should be avoided.
+ */
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.FUNCTION)
+annotation class DelicateCollektiveApi
+
 /**
  * Models the minimal set of aggregate operations.
  * Holds the [localId] of the device executing the aggregate program.
@@ -40,6 +49,7 @@ interface Aggregate<ID : Any> {
      * The result of the exchange function is a field with as messages a map with key the id of devices across the
      * network and the result of the computation passed as relative local values.
      */
+    @DelicateCollektiveApi
     fun <Initial> exchange(
         initial: Initial,
         dataSharingMethod: DataSharingMethod<Initial>,
@@ -57,6 +67,7 @@ interface Aggregate<ID : Any> {
      * }
      * ```
      */
+    @DelicateCollektiveApi
     fun <Initial, Return> exchanging(
         initial: Initial,
         dataSharingMethod: DataSharingMethod<Initial>,
@@ -99,6 +110,7 @@ interface Aggregate<ID : Any> {
      * In this case, the field returned has the computation as a result,
      * in form of a field of functions with type `() -> Int`.
      */
+    @DelicateCollektiveApi
     fun <Scalar> neighboring(
         local: Scalar,
         dataSharingMethod: DataSharingMethod<Scalar>,
@@ -142,23 +154,29 @@ interface Aggregate<ID : Any> {
         /**
          * Inlined version of the [Aggregate.exchange] function.
          */
+
         inline fun <ID : Any, reified Initial> Aggregate<ID>.exchange(
             initial: Initial,
             noinline body: (Field<ID, Initial>) -> Field<ID, Initial>,
-        ): Field<ID, Initial> = exchange(initial, dataSharingMethod(), body)
+        ): Field<ID, Initial> =
+            @OptIn(DelicateCollektiveApi::class)
+            exchange(initial, dataSharingMethod(), body)
 
         /**
          * Inlined version of the [Aggregate.exchanging] function.
          */
         inline fun <ID : Any, reified Initial, Return> Aggregate<ID>.exchanging(
             initial: Initial,
             noinline body: YieldingScope<Field<ID, Initial>, Field<ID, Return>>,
-        ): Field<ID, Return> = exchanging(initial, dataSharingMethod(), body)
+        ): Field<ID, Return> =
+            @OptIn(DelicateCollektiveApi::class)
+            exchanging(initial, dataSharingMethod(), body)
 
         /**
          * Inlined version of the [Aggregate.neighboring] function.
          */
         inline fun <ID : Any, reified Scalar> Aggregate<ID>.neighboring(local: Scalar): Field<ID, Scalar> =
+            @OptIn(DelicateCollektiveApi::class)
             neighboring(local, dataSharingMethod())
     }
 }
diff --git a/dsl/src/commonMain/kotlin/it/unibo/collektive/aggregate/api/impl/AggregateContext.kt b/dsl/src/commonMain/kotlin/it/unibo/collektive/aggregate/api/impl/AggregateContext.kt
@@ -3,6 +3,7 @@ package it.unibo.collektive.aggregate.api.impl
 import it.unibo.collektive.aggregate.api.Aggregate
 import it.unibo.collektive.aggregate.api.Aggregate.Companion.neighboring
 import it.unibo.collektive.aggregate.api.DataSharingMethod
+import it.unibo.collektive.aggregate.api.DelicateCollektiveApi
 import it.unibo.collektive.aggregate.api.YieldingContext
 import it.unibo.collektive.aggregate.api.YieldingResult
 import it.unibo.collektive.aggregate.api.YieldingScope
@@ -48,12 +49,14 @@ internal class AggregateContext<ID : Any>(
         others: Map<ID, T>,
     ): Field<ID, T> = Field(localId, localValue, others)
 
+    @DelicateCollektiveApi
     override fun <Initial> exchange(
         initial: Initial,
         dataSharingMethod: DataSharingMethod<Initial>,
         body: (Field<ID, Initial>) -> Field<ID, Initial>,
     ): Field<ID, Initial> = exchanging(initial, dataSharingMethod) { field -> body(field).run { yielding { this } } }
 
+    @DelicateCollektiveApi
     override fun <Initial, Ret> exchanging(
         initial: Initial,
         dataSharingMethod: DataSharingMethod<Initial>,
@@ -93,6 +96,7 @@ internal class AggregateContext<ID : Any>(
             }.toReturn
     }
 
+    @DelicateCollektiveApi
     override fun <Scalar> neighboring(
         local: Scalar,
         dataSharingMethod: DataSharingMethod<Scalar>,