1 //: Continuations are a powerful primitive for constructing advanced kinds of
  2 //: control *policies* like back-tracking.
  3 //:
  4 //: In Mu, continuations are first-class and delimited, and are constructed
  5 //: out of two primitives:
  6 //:
  7 //:  * 'call-with-continuation-mark' marks the top of the call stack and then
  8 //:    calls the provided recipe.
  9 //:  * 'return-continuation-until-mark' copies the top of the stack
 10 //:    until the mark, and returns it as the result of
 11 //:    'call-with-continuation-mark' (which might be a distant ancestor on the
 12 //:    call stack; intervening calls don't return)
 13 //:
 14 //: The resulting slice of the stack can now be called just like a regular
 15 //: recipe.
 16 //:
 17 //: See the example programs continuation*.mu to get a sense for the
 18 //: possibilities.
 19 //:
 20 //: Refinements:
 21 //:  * You can call a single continuation multiple times, and it will preserve
 22 //:    the state of its local variables at each stack frame between calls.
 23 //:    The stack frames of a continuation are not destroyed until the
 24 //:    continuation goes out of scope. See continuation2.mu.
 25 //:  * 'return-continuation-until-mark' doesn't consume the mark, so you can
 26 //:    return multiple continuations based on a single mark. In combination
 27 //:    with the fact that 'return-continuation-until-mark' can return from
 28 //:    regular calls, just as long as there was an earlier call to
 29 //:    'call-with-continuation-mark', this gives us a way to create resumable
 30 //:    recipes. See continuation3.mu.
 31 //:  * 'return-continuation-until-mark' can take ingredients to return just
 32 //:    like other 'return' instructions. It just implicitly also returns a
 33 //:    continuation as the first result. See continuation4.mu.
 34 //:  * Conversely, you can pass ingredients to a continuation when calling it,
 35 //:    to make it available to products of 'return-continuation-until-mark'.
 36 //:    See continuation5.mu.
 37 //:  * There can be multiple continuation marks on the stack at once;
 38 //:    'call-with-continuation-mark' and 'return-continuation-until-mark' both
 39 //:    need to pass in a tag to coordinate on the correct mark. This allows us
 40 //:    to save multiple continuations for different purposes (say if one is
 41 //:    for exceptions) with overlapping stack frames. See exception.mu.
 42 //:
 43 //: Inspired by James and Sabry, "Yield: Mainstream delimited continuations",
 44 //: Workshop on the Theory and Practice of Delimited Continuations, 2011.
 45 //: https://www.cs.indiana.edu/~sabry/papers/yield.pdf
 46 //:
 47 //: Caveats:
 48 //:  * At the moment we can't statically type-check continuations. So we raise
 49 //:    runtime errors for a call that doesn't return a continuation when the
 50 //:    caller expects, or one that returns a continuation when the caller
 51 //:    doesn't expect it. This shouldn't cause memory corruption, though.
 52 //:    There should still be no way to lookup addresses that aren't allocated.
 53 
 54 :(before "End Mu Types Initialization")
 55 type_ordinal continuation = Type_ordinal["continuation"] = Next_type_ordinal++;
 56 Type[continuation].name = "continuation";
 57 
 58 //: A continuation can be called like a recipe.
 59 :(before "End is_mu_recipe Atom Cases(r)")
 60 if (r.type->name == "continuation") return true;
 61 
 62 //: However, it can't be type-checked like most recipes. Pretend it's like a
 63 //: header-less recipe.
 64 :(after "Begin Reagent->Recipe(r, recipe_header)")
 65 if (r.type->atom && r.type->name == "continuation") {
 66   result_header.has_header = false;
 67   return result_header;
 68 }
 69 
 70 :(scenario delimited_continuation)
 71 recipe main [
 72   1:continuation <- call-with-continuation-mark 233/mark, f, 77  # 77 is an argument to f
 73   2:num <- copy 5
 74   {
 75     2:num <- call 1:continuation, 2:num  # jump to 'return-continuation-until-mark' below
 76     3:bool <- greater-or-equal 2:num, 8
 77     break-if 3:bool
 78     loop
 79   }
 80 ]
 81 recipe f [
 82   11:num <- next-ingredient
 83   12:num <- g 11:num
 84   return 12:num
 85 ]
 86 recipe g [
 87   21:num <- next-ingredient
 88   22:num <- return-continuation-until-mark 233/mark
 89   23:num <- add 22:num, 1
 90   return 23:num
 91 ]
 92 # first call of 'g' executes the part before return-continuation-until-mark
 93 +mem: storing 77 in location 21
 94 +run: {2: "number"} <- copy {5: "literal"}
 95 +mem: storing 5 in location 2
 96 # calls of the continuation execute the part after return-continuation-until-mark
 97 +run: {2: "number"} <- call {1: "continuation"}, {2: "number"}
 98 +mem: storing 5 in location 22
 99 +mem: storing 6 in location 2
100 +run: {2: "number"} <- call {1: "continuation"}, {2: "number"}
101 +mem: storing 6 in location 22
102 +mem: storing 7 in location 2
103 +run: {2: "number"} <- call {1: "continuation"}, {2: "number"}
104 +mem: storing 7 in location 22
105 +mem: storing 8 in location 2
106 # first call of 'g' does not execute the part after return-continuation-until-mark
107 -mem: storing 77 in location 22
108 # calls of the continuation don't execute the part before return-continuation-until-mark
109 -mem: storing 5 in location 21
110 -mem: storing 6 in location 21
111 -mem: storing 7 in location 21
112 # termination
113 -mem: storing 9 in location 2
114 
115 :(before "End call Fields")
116 int continuation_mark_tag;
117 :(before "End call Constructor")
118 continuation_mark_tag = 0;
119 
120 :(before "End Primitive Recipe Declarations")
121 CALL_WITH_CONTINUATION_MARK,
122 :(before "End Primitive Recipe Numbers")
123 Recipe_ordinal["call-with-continuation-mark"] = CALL_WITH_CONTINUATION_MARK;
124 :(before "End Primitive Recipe Checks")
125 case CALL_WITH_CONTINUATION_MARK: {
126   if (SIZE(inst.ingredients) < 2) {
127     raise << maybe(get(Recipe, r).name) << "'" << to_original_string(inst) << "' requires at least two ingredients: a mark number and a recipe to call\n" << end();
128   }
129   break;
130 }
131 :(before "End Primitive Recipe Implementations")
132 case CALL_WITH_CONTINUATION_MARK: {
133   // like call, but mark the current call as a 'base of continuation' call
134   // before pushing the next one on it
135   if (Trace_stream) {
136     ++Trace_stream->callstack_depth;
137     trace("trace") << "delimited continuation; incrementing callstack depth to " << Trace_stream->callstack_depth << end();
138     assert(Trace_stream->callstack_depth < 9000);  // 9998-101 plus cushion
139   }
140   instruction/*copy*/ caller_instruction = current_instruction();
141   Current_routine->calls.front().continuation_mark_tag = current_instruction().ingredients.at(0).value;
142   Current_routine->calls.push_front(call(ingredients.at(1).at(0)));
143   // drop the mark
144   caller_instruction.ingredients.erase(caller_instruction.ingredients.begin());
145   ingredients.erase(ingredients.begin());
146   // drop the callee
147   caller_instruction.ingredients.erase(caller_instruction.ingredients.begin());
148   ingredients.erase(ingredients.begin());
149   finish_call_housekeeping(caller_instruction, ingredients);
150   continue;
151 }
152 
153 :(scenario next_ingredient_inside_continuation)
154 recipe main [
155   call-with-continuation-mark 233/mark, f, true
156 ]
157 recipe f [
158   10:bool <- next-input
159 ]
160 +mem: storing 1 in location 10
161 
162 :(scenario delimited_continuation_out_of_recipe_variable)
163 recipe main [
164   x:recipe <- copy f
165   call-with-continuation-mark 233/mark, x, true
166 ]
167 recipe f [
168   10:bool <- next-input
169 ]
170 +mem: storing 1 in location 10
171 
172 //: save the slice of current call stack until the 'call-with-continuation-mark'
173 //: call, and return it as the result.
174 //: todo: implement delimited continuations in Mu's memory
175 :(before "End Types")
176 struct delimited_continuation {
177   call_stack frames;
178   int nrefs;
179   delimited_continuation(call_stack::iterator begin, call_stack::iterator end) :frames(call_stack(begin, end)), nrefs(0) {}
180 };
181 :(before "End Globals")
182 map<long long int, delimited_continuation> Delimited_continuation;
183 long long int Next_delimited_continuation_id = 1;  // 0 is null just like an address
184 :(before "End Reset")
185 Delimited_continuation.clear();
186 Next_delimited_continuation_id = 1;
187 
188 :(before "End Primitive Recipe Declarations")
189 RETURN_CONTINUATION_UNTIL_MARK,
190 :(before "End Primitive Recipe Numbers")
191 Recipe_ordinal["return-continuation-until-mark"] = RETURN_CONTINUATION_UNTIL_MARK;
192 :(before "End Primitive Recipe Checks")
193 case RETURN_CONTINUATION_UNTIL_MARK: {
194   if (inst.ingredients.empty()) {
195     raise << maybe(get(Recipe, r).name) << "'" << to_original_string(inst) << "' requires at least one ingredient: a mark tag (number)\n" << end();
196   }
197   break;
198 }
199 :(before "End Primitive Recipe Implementations")
200 case RETURN_CONTINUATION_UNTIL_MARK: {
201   // I don't know how to think about next-ingredient in combination with
202   // continuations, so seems cleaner to just kill it. Functions have to read
203   // their inputs before ever returning a continuation.
204   Current_routine->calls.front().ingredient_atoms.clear();
205   Current_routine->calls.front().next_ingredient_to_process = 0;
206   // copy the current call stack until the most recent marked call
207   call_stack::iterator find_base_of_continuation(call_stack&, int);  // manual prototype containing '::'
208   call_stack::iterator base = find_base_of_continuation(Current_routine->calls, /*mark tag*/current_instruction().ingredients.at(0).value);
209   if (base == Current_routine->calls.end()) {
210     raise << maybe(current_recipe_name()) << "couldn't find a 'call-with-continuation-mark' to return to with tag " << current_instruction().ingredients.at(0).original_string << '\n' << end();
211     raise << maybe(current_recipe_name()) << "call stack:\n" << end();
212     for (call_stack::iterator p = Current_routine->calls.begin();  p != Current_routine->calls.end();  ++p)
213       raise << maybe(current_recipe_name()) << "  " << get(Recipe, p(base_type);
:(after "Update PUT base_type in Run")
base_type = get_base_type(base_type);
:(after "Update MAYBE_CONVERT base_type in Check")
base_type = get_base_type(base_type);
:(after "Update base_type in size_of(type)")
base_type = get_base_type(base_type);
:(after "Update base_type in element_type")
base_type = get_base_type(base_type);
:(after "Update base_type in compute_container_address_offsets")
base_type = get_base_type(base_type);
:(after "Update base_type in append_container_address_offsets")
base_type = get_base_type(base_type);
:(after "Update element_base_type For Exclusive Container in append_addresses")
element_base_type = get_base_type(element_base_type);
:(after "Update base_type in skip_addresses")
base_type = get_base_type(base_type);
:(replace{} "const type_tree* get_base_type(const type_tree* t)")
const type_tree* get_base_type(const type_tree* t) {
  const type_tree* result = t->atom ? t : t->left;
  if (!result->atom)
    raise << "invalid type " << to_string(t) << '\n' << end();
  return result;
}

:(scenario ill_formed_container)
% Hide_errors = true;
def main [
  {1: ((foo) num)} <- copy 0
]
# no crash

:(scenario size_of_shape_shifting_container)
container foo:_t [
  x:_t
  y:num
]
def main [
  1:foo:num <- merge 12, 13
  3:foo:point <- merge 14, 15, 16
]
+mem: storing 12 in location 1
+mem: storing 13 in location 2
+mem: storing 14 in location 3
+mem: storing 15 in location 4
+mem: storing 16 in location 5

:(scenario size_of_shape_shifting_container_2)
# multiple type ingredients
container foo:_a:_b [
  x:_a
  y:_b
]
def main [
  1:foo:num:bool <- merge 34, 1/true
]
$error: 0

:(scenario size_of_shape_shifting_container_3)
container foo:_a:_b [
  x:_a
  y:_b
]
def main [
  1:text <- new [abc]
  # compound types for type ingredients
  {2: (foo number (address array character))} <- merge 34/x, 1:text/y
]
$error: 0

:(scenario size_of_shape_shifting_container_4)
container foo:_a:_b [
  x:_a
  y:_b
]
container bar:_a:_b [
  # dilated element
  {data: (foo _a (address _b))}
]
def main [
  1:text <- new [abc]
  2:bar:num:@:char <- merge 34/x, 1:text/y
]
$error: 0

:(scenario shape_shifting_container_extend)
container foo:_a [
  x:_a
]
container foo:_a [
  y:_a
]
$error: 0

:(scenario shape_shifting_container_extend_error)
% Hide_errors = true;
container foo:_a [
  x:_a
]
container foo:_b [
  y:_b
]
+error: headers of container 'foo' must use identical type ingredients

:(scenario type_ingredient_must_start_with_underscore)
% Hide_errors = true;
container foo:t [
  x:num
]
+error: foo: type ingredient 't' must begin with an underscore

:(before "End Globals")
// We'll use large type ordinals to mean "the following type of the variable".
// For example, if we have a generic type called foo:_elem, the type
// ingredient _elem in foo's type_info will have value START_TYPE_INGREDIENTS,
// and we'll handle it by looking in the current reagent for the next type
// that appears after foo.
extern const int START_TYPE_INGREDIENTS = 2000;
:(before "End Commandline Parsing")  // after loading .mu files
assert(Next_type_ordinal < START_TYPE_INGREDIENTS);

:(before "End type_info Fields")
map<string, type_ordinal> type_ingredient_names;

//: Suppress unknown type checks in shape-shifting containers.

:(before "Check Container Field Types(info)")
if (!info.type_ingredient_names.empty()) continue;

:(before "End container Name Refinements")
if (name.find(':') != string::npos) {
  trace(9999, "parse") << "container has type ingredients; parsing" << end();
  if (!read_type_ingredients(name, command)) {
    // error; skip rest of the container definition and continue
    slurp_balanced_bracket(in);
    return;
  }
}

:(code)
bool read_type_ingredients(string& name, const string& command) {
  string save_name = name;
  istringstream in(save_name);
  name = slurp_until(in, ':');
  map<string, type_ordinal> type_ingredient_names;
  if (!slurp_type_ingredients(in, type_ingredient_names, name)) {
    return false;
  }
  if (contains_key(Type_ordinal, name)
      && contains_key(Type, get(Type_ordinal, name))) {
    const type_info& previous_info = get(Type, get(Type_ordinal, name));
    // we've already seen this container; make sure type ingredients match
    if (!type_ingredients_match(