From 3c363a945c162a6fe9a965248b3f215aeeaee90f Mon Sep 17 00:00:00 2001
From: heck <heck@pep.foundation>
Date: Wed, 7 Jun 2023 12:09:32 +0200
Subject: [PATCH] lms-c99 - param modes, use terminology
 (M)BORROW/CLAIM/PROVIDE

---
 lm-c99/lms-c99.md | 41 ++++++++++++++++++++---------------------
 1 file changed, 20 insertions(+), 21 deletions(-)

diff --git a/lm-c99/lms-c99.md b/lm-c99/lms-c99.md
index ddf47d8..1e3b3fe 100644
--- a/lm-c99/lms-c99.md
+++ b/lm-c99/lms-c99.md
@@ -16,15 +16,14 @@
     * [Parameter Passing Modes](#parameter-passing-modes)
       * [Mapping Table for C](#mapping-table-for-c)
       * [Rules For Parameters Of Primitive-Type](#rules-for-parameters-of-primitive-type)
-    * [Update](#update)
+    * [MBORROW](#mborrow)
       * [Rules For Parameters Of Object-Type](#rules-for-parameters-of-object-type)
-        * [Read](#read)
-        * [Update](#update-1)
-        * [Consume](#consume)
-        * [Produce](#produce)
+        * [BORROW](#borrow)
+        * [MBORROW](#mborrow-1)
+        * [CLAIM](#claim)
+        * [PROVIDE](#provide)
       * [Rules For Multithreading](#rules-for-multithreading)
 <!-- TOC -->
-
 This is the document specifying the pEpACIDLang language mapping for C99.
 
 C99, because this is the minimum language level for the generated target code.
@@ -38,7 +37,7 @@ The interface generator implements parts of the language mapping specification.
 State: Draft, to be reviewed with fdik and positron.
 
 **ATTENTION, IMPORTANT**   
-In this document, all types expressed as T are the IDL-types, not their corresponding c-types.    
+In this document, all types expressed as `T` are the IDL-types, not their corresponding c-types.    
 An example for clarity:   
 If `T` is the type `string`, the IDL-type `string` is meant, so the c-type of `T*` is `char**`.
 
@@ -85,7 +84,7 @@ For any object-type `T`, corresponding `new` and `free` methods are being genera
 To create an object of type `T` correctly, there are two ways:
 
 1. Using its allocator-method
-2. Using any method that has a parameter of type `T` with mode `Produce`
+2. Using any method that has a parameter of type `T` with mode `PROVIDE`
 
 To destroy an object of type `T` correctly, the only way is to use its destructor-method.
 
@@ -124,7 +123,7 @@ The main concerns when sharing memory (e.g. in form of parameters) are:
 In environments where memory management is explicit, the lifecycle of data in memory is:
 
 1. Memory being allocated
-2. Memory being shared with producers/consumers (e.g. as a parameter Read/Update/Consume)
+2. Memory being shared with producers/consumers (e.g. as a parameter `BORROW`/`MBORROW`/`CLAIM`)
 3. Read/write operations by multiple parties (needs synchronization if multithreaded environment)
 3. Make sure this memory will never be accessed again by nobody
 4. Memory has to be freed exactly once and compatibly to how it was allocated
@@ -145,26 +144,26 @@ These rules apply regardless of the parameter passing mode.
 
 The modes are named by describing what the callee does, from the perspective of the callee, using one verb.
 
-* `Read` - Immutable, ownership remains with caller
-* `Update` - Mutable, ownership remains with caller
-* `Consume` - Mutable, ownership goes to callee
-* `Produce` - Immutable, ownership goes to caller
+* `BORROW` - Immutable, ownership remains with caller
+* `MBORROW` - Mutable, ownership remains with caller
+* `CLAIM` - Mutable, ownership goes to callee
+* `PROVIDE` - Immutable, ownership goes to caller
 
 #### Mapping Table for C
 
 Type of `T` as a function of type-class and mode.
 Where `T` any of the respective IDL-Types (not their respective c-type, as mentioned in [About This Document](#about-this-document)).
 
-| Mode/Type-Class  | READ | UPDATE | CONSUME | PRODUCE |
+| Mode/Type-Class  | BORROW | MBORROW | CLAIM | PROVIDE |
 |------------------|------|--------|---------|---------|
 | Primitive        | T    | T*     | - (1)   | - (1)   |
 | Object           | T    | T*     | T       | T*      |  
 
 #### Rules For Parameters Of Primitive-Type
 
-(1) A primitive-type cannot be consumed or produced because it's always statically allocated.
+(1) A primitive-type cannot be claimed or provided because it's always statically allocated.
 
-### Update
+### MBORROW
 
 The caller has to allocate memory for `T*`.   
 The callee is allowed to mutate the memory pointed to by `T*`.   
@@ -172,7 +171,7 @@ The caller is responsible to free the memory pointed to by `T*`.
 
 #### Rules For Parameters Of Object-Type
 
-##### Read
+##### BORROW
 
 The caller has to guarantee that either-or:
 
@@ -183,7 +182,7 @@ The caller has to guarantee that either-or:
 The callee is not allowed to mutate or free any memory that can be reached through `T`.
 The caller is responsible to free all the memory that can be reached through `T`.
 
-##### Update
+##### MBORROW
 
 The caller has to guarantee that:
 
@@ -208,12 +207,12 @@ The caller must free `T` and any of its transitive members.
 
 TODO: Upon any failure of the method call:
 
-##### Consume
+##### CLAIM
 
-The same rules for mode `Read` apply, with the exception that the caller has to guarantee to never access `T` again in
+The same rules for mode `BORROW` apply, with the exception that the caller has to guarantee to never access `T` again in
 any way.
 
-##### Produce
+##### PROVIDE
 
 The caller is allowed to pass a `T*` with an undefined value.   
 TODO...