feat(regions): retargeting of returned literals into argument region

Author: radovanhorvat

docs/overview/08-memory-management.md

@@ -106,7 +106,7 @@ struct Point:
 end
 
 func make_point(x, y, r: Region) -> Point:
-    return Point{x = x, y = y}[r]    // OK: allocated caller-provided region 
+    return Point{x = x, y = y}[r]    // OK: allocated in caller-provided region
 end
 
 func bad_point(x, y) -> Point:
@@ -397,7 +397,39 @@ func main():
 end
 ```
 
-#### 8.5.3 Nested composite literals
+#### 8.5.3 Returned literal retargeting
+
+For a composite-returning function, the same-region rule determines a shared
+caller-owned result region from its non-`foreign` composite parameters and
+`Region` parameters. A composite literal used directly as a return expression
+is automatically allocated in that region:
+
+```jik
+func display_name(user: Person) -> String:
+    if user.name == "":
+        return "Anonymous"     // allocated in user's region
+    end
+    return user.name
+end
+
+func make_point(x, y, r: Region) -> Point:
+    return Point{x = x, y = y}     // allocated in r
+end
+```
+
+This rule applies only to a directly returned composite literal. It does not
+retarget a local variable, a literal with an explicit allocation specifier, a
+`foreign` value, or a global value. Without an eligible parameter, returning a
+local literal remains an error. Explicit allocation remains valid when it
+improves clarity:
+
+```jik
+func make_point_explicit(x, y, r: Region) -> Point:
+    return Point{x = x, y = y}[r]
+end
+```
+
+#### 8.5.4 Nested composite literals
 
 Composite literals that contain other composite values must be internally region-consistent.
 The outer value and the contained composite values must belong to the same region.
@@ -426,7 +458,7 @@ func foo(v: Vec[String]):
 end
 ```
 
-#### 8.5.4 Temporary containers passed to `foreign` parameters
+#### 8.5.5 Temporary containers passed to `foreign` parameters
 
 A temporary `Vec` or `Dict` literal passed directly to a `foreign` parameter
 may contain composite elements from different regions. This exception applies
@@ -459,7 +491,7 @@ Since `args` in `process::capture` is a `foreign` vector, at the call site the e
 need not be in the same region.
 
 
-#### 8.5.5 Region-safe builtins
+#### 8.5.6 Region-safe builtins
 
 All currently provided builtins except `push` are region-safe, so their calls
 do not need to satisfy the same-region rule. Some only inspect their composite

examples/README.md

@@ -8,19 +8,20 @@ standard library.
 1. `hello.jik` - the smallest complete Jik program
 2. `fib.jik` - functions, loops, recursion, and region-based allocation
 3. `regions_copy.jik` - returning copied composite values in a caller-chosen region
-4. `primes.jik` - loops and vectors
-5. `word_count.jik` - structs, file I/O, and standard library use
-6. `text_processing.jik` - string/vector slices, indexed iteration, and comparisons
-7. `modules/main.jik` - multi-file programs, modules, and imports
-8. `enum_match.jik` - exhaustive matching over enum values
-9. `variants.jik` - enums, payload-less variants, `match`, and UFCS
-10. `tables.jik` - exhaustive enum lookup tables and table-driven transitions
-11. `error_handling.jik` - `throws`, recovery, propagation, `must`, and postfix `!`
-12. `ffi_demo.jik` - calling C functions and opaque C structs through Jik's FFI
-13. `testing_demo.jik` - basic use of `jik/testing`
-14. `cl_args.jik` - raw command-line argument handling
-15. `argparse_demo.jik` - parsed arguments, generated help, and path normalization
-16. `process_capture.jik` - capture a process and inspect stdout/stderr
+4. `region_ergonomics.jik` - inferred regions for returned, nested, and stored literals
+5. `primes.jik` - loops and vectors
+6. `word_count.jik` - structs, file I/O, and standard library use
+7. `text_processing.jik` - string/vector slices, indexed iteration, and comparisons
+8. `modules/main.jik` - multi-file programs, modules, and imports
+9. `enum_match.jik` - exhaustive matching over enum values
+10. `variants.jik` - enums, payload-less variants, `match`, and UFCS
+11. `tables.jik` - exhaustive enum lookup tables and table-driven transitions
+12. `error_handling.jik` - `throws`, recovery, propagation, `must`, and postfix `!`
+13. `ffi_demo.jik` - calling C functions and opaque C structs through Jik's FFI
+14. `testing_demo.jik` - basic use of `jik/testing`
+15. `cl_args.jik` - raw command-line argument handling
+16. `argparse_demo.jik` - parsed arguments, generated help, and path normalization
+17. `process_capture.jik` - capture a process and inspect stdout/stderr
 
 The remaining examples are larger demonstrations:
 

examples/region_ergonomics.jik

@@ -0,0 +1,44 @@
+// Example: region ergonomics in Jik.
+
+struct User:
+    name: String
+    labels: Vec[String]
+end
+
+
+func new_user(foreign name: String, r: Region) -> User:
+    // The returned struct and its composite field `labels` are automatically
+    // allocated in r, since this is the only possible valid allocation destination.
+    // Since `name` is marked as a foreign parameter, we still need to copy it to `r`.
+    return User{
+        name = copy(name, r),
+        labels = ["new", "active"]
+    }
+end
+
+
+func display_name(user: User) -> String:
+    if user.name == "":
+        // The returned string literal is allocated in user's region, since
+        // this is the only valid destination.
+        return "Anonymous"
+    end
+    return user.name
+end
+
+
+func add_default_label(user: User):
+    // The string literal is automatically allocated in user's region.
+    // This is also valid for other store operations involving composite values.
+    push(user.labels, "member")
+end
+
+
+func main():
+    // An omitted final Region argument automatically passes the current
+    // function's local region `_`.
+    user := new_user("Ada")
+
+    add_default_label(user)
+    println(display_name(user), ": ", user.labels)
+end

src/jik/regcheck.c

@@ -622,6 +622,29 @@ jik_alloc_spec_complete(JikAllocSpec s)
     return s.kind != JIK_ALLOC_UNKNOWN && s.src != JIK_ALLOC_SRC_UNKNOWN;
 }
 
+static JikAllocSpec *
+get_function_implicit_region_spec(JikNode *func_nd, TabJikAllocSpec *spec_tab)
+{
+    assert(func_nd->type == NODE_FUNCTION);
+    if (!jik_type_is_allocated(func_nd->jik_type->val_func.ret_type)) {
+        return NULL;
+    }
+
+    for (size_t i = 0; i < VecJikNode_size(func_nd->val_function.params); i++) {
+        JikNode *param = VecJikNode_get(func_nd->val_function.params, i);
+        if (param->jik_type != &JIK_TYPE_REGION &&
+            (!jik_type_is_allocated(param->jik_type) || param->val_id.is_foreign)) {
+            continue;
+        }
+
+        JikAllocSpec *spec = TabJikAllocSpec_get(spec_tab, param->val_id.name);
+        if (spec && jik_alloc_spec_complete(*spec)) {
+            return spec;
+        }
+    }
+    return NULL;
+}
+
 static bool
 jik_alloc_sources_match(JikAllocSpec s1, JikAllocSpec s2)
 {
@@ -1021,18 +1044,27 @@ jik_check_region_integrity(JikNode *ast)
                 if (!jik_type_is_allocated(nd->val_return.expr->jik_type)) {
                     continue;
                 }
-                JikAllocSpec spec = get_expression_alloc_spec(nd->val_return.expr, spec_tab);
+                JikNode     *expr = nd->val_return.expr;
+                JikAllocSpec spec = get_expression_alloc_spec(expr, spec_tab);
+                if (jik_node_is_allocated_literal(expr) && spec.src == JIK_ALLOC_SRC_LOCAL) {
+                    JikAllocSpec *implicit_spec =
+                        get_function_implicit_region_spec(func_nd, spec_tab);
+                    if (implicit_spec && can_retarget_literal(expr, *implicit_spec)) {
+                        jik_set_alloc_spec(expr, *implicit_spec);
+                        spec = get_expression_alloc_spec(expr, spec_tab);
+                    }
+                }
                 if (jik_alloc_source_known(spec) && spec.src == JIK_ALLOC_SRC_LOCAL) {
                     jik_diag_fatal_error("cannot return local allocation",
-                                         jik_token_to_text(nd->val_return.expr->token));
+                                         jik_token_to_text(expr->token));
                 }
                 else if (jik_alloc_source_known(spec) && spec.src == JIK_ALLOC_SRC_CROSS) {
                     jik_diag_fatal_error("cannot return foreign composite value",
-                                         jik_token_to_text(nd->val_return.expr->token));
+                                         jik_token_to_text(expr->token));
                 }
                 else if (jik_alloc_source_known(spec) && spec.kind == JIK_ALLOC_GLOBAL) {
                     jik_diag_fatal_error("cannot return composite global",
-                                         jik_token_to_text(nd->val_return.expr->token));
+                                         jik_token_to_text(expr->token));
                 }
             }
             else if (jik_node_is_allocated_literal(nd)) {