Allow programmatic override of the default runtime options (ponylang#…

…3342)

Prior to this commit, the only way to override the default pony
runtime options was via the command line.

This commit allows for programmatic override of the default pony
runtime options via a specific bare function created on the Main
actor:

`fun @runtime_override_defaults(rto: RuntimeOptions) => None`

In order to override the values, a programmer would replace the
`None` with logic to directly set the various options on the `rto`
variable. This bare function is limited in what is allowed and
is only allowed to call functions on `primitive`s to ensure no
memory allocation occurs as it is called before the runtime is
fully initialized.

This commit also renames the internal variable in `options_t` from
`nopin` to `pin` to better align with how it is set from the
command line so it is easier to programmatically change.

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to the Pony compiler and standard library will be documented
 
 ### Added
 
+- Allow programmatic override of the default runtime options ([PR #3342](https://github.com/ponylang/ponyc/pull/3342))
 
 ### Changed
 

packages/builtin/runtime_options.pony

@@ -0,0 +1,115 @@
+struct RuntimeOptions
+  """
+  Pony struct for the Pony runtime options C struct that can be used to
+  override the Pony runtime defaults via code compiled into the program.
+
+  The way this is done is by adding the following function to your `Main` actor:
+
+  ```
+    fun @runtime_override_defaults(rto: RuntimeOptions) =>
+  ```
+
+  and then overriding the fields of `rto` (the `RuntimeOptions` instance) as
+  needed.
+
+  NOTE: Command line arguments still any values set via
+        `@runtime_override_defaults`.
+
+
+  The following example overrides the `--ponyhelp` argument to default it to
+  `true` instead of `false` causing the compiled program to always display
+  the Pony runtime help:
+
+  ```
+  actor Main
+    new create(env: Env) =>
+      env.out.print("Hello, world.")
+
+    fun @runtime_override_defaults(rto: RuntimeOptions) =>
+      rto.ponyhelp = true
+  ```
+  """
+
+/* NOTE: if you change any of the field docstrings, update `options.h` in
+ *       the runtime to keep them in sync.
+ */
+
+  var ponymaxthreads: U32 = 0
+    """
+    Use N scheduler threads. Defaults to the number of cores (not hyperthreads)
+    available.
+    This can't be larger than the number of cores available.
+    """
+
+  var ponyminthreads: U32 = 0
+    """
+    Minimum number of active scheduler threads allowed.
+    Defaults to 0, meaning that all scheduler threads are allowed to be
+    suspended when no work is available.
+    This can't be larger than --ponymaxthreads if provided, or the physical
+    cores available.
+    """
+
+  var ponynoscale: Bool = false
+    """
+    Don't scale down the scheduler threads.
+    See --ponymaxthreads on how to specify the number of threads explicitly.
+    Can't be used with --ponyminthreads.
+    """
+
+  var ponysuspendthreshold: U32 = 0
+    """
+    Amount of idle time before a scheduler thread suspends itself to minimize
+    resource consumption (max 1000 ms, min 1 ms).
+    Defaults to 1 ms.
+    """
+
+  var ponycdinterval: U32 = 100
+    """
+    Run cycle detection every N ms (max 1000 ms, min 10 ms).
+    Defaults to 100 ms.
+    """
+
+  var ponygcinitial: USize = 14
+    """
+    Defer garbage collection until an actor is using at least 2^N bytes.
+    Defaults to 2^14.
+    """
+
+  var ponygcfactor: F64 = 2.0
+    """
+    After GC, an actor will next be GC'd at a heap memory usage N times its
+    current value. This is a floating point value. Defaults to 2.0.
+    """
+
+  var ponynoyield: Bool = false
+    """
+    Do not yield the CPU when no work is available.
+    """
+
+  var ponynoblock: Bool = false
+    """
+    Do not send block messages to the cycle detector.
+    """
+
+  var ponypin: Bool = false
+    """
+    Pin scheduler threads to CPU cores. The ASIO thread can also be pinned if
+    `--ponypinasio` is set.
+    """
+
+  var ponypinasio: Bool = false
+    """
+    Pin the ASIO thread to a CPU the way scheduler threads are pinned to CPUs.
+    Requires `--ponypin` to be set to have any effect.
+    """
+
+  var ponyversion: Bool = false
+    """
+    Print the version of the compiler and exit.
+    """
+
+  var ponyhelp: Bool = false
+    """
+    Print the runtime usage options and exit.
+    """

src/libponyc/codegen/genexe.c

@@ -527,6 +527,7 @@ bool genexe(compile_t* c, ast_t* program)
   if(c->opt->verbosity >= VERBOSITY_INFO)
     fprintf(stderr, " Reachability\n");
   reach(c->reach, main_ast, c->str_create, NULL, c->opt);
+  reach(c->reach, main_ast, stringtab("runtime_override_defaults"), NULL, c->opt);
   reach(c->reach, env_ast, c->str__create, NULL, c->opt);
 
   if(c->opt->limit == PASS_REACH)

src/libponyc/pass/sugar.c

@@ -17,6 +17,28 @@
 #include <string.h>
 
 
+static ast_t* make_runtime_override_defaults(ast_t* ast)
+{
+  pony_assert(ast != NULL);
+
+  // set it as a bare function
+  token_id cap = TK_AT;
+
+  BUILD(runtime_override_defaults, ast,
+    NODE(TK_FUN, AST_SCOPE
+      NODE(cap)
+      ID("runtime_override_defaults")  // name
+      NONE          // typeparams
+      NODE(TK_PARAMS, NODE(TK_PARAM, ID("rto") NODE(TK_NOMINAL, ID("$0") ID("RuntimeOptions") NONE NONE NONE) NONE))          // params
+      NONE          // return type
+      NONE          // error
+      NODE(TK_SEQ, NODE(TK_TRUE))
+      NONE
+      ));
+
+  return runtime_override_defaults;
+}
+
 static ast_t* make_create(ast_t* ast)
 {
   pony_assert(ast != NULL);
@@ -82,6 +104,19 @@ bool has_member(ast_t* members, const char* name)
 }
 
 
+static void add_default_runtime_override_defaults_method(ast_t* ast)
+{
+  pony_assert(ast != NULL);
+  ast_t* members = ast_childidx(ast, 4);
+
+  // If have no @runtime_override_defaults method, add one.
+  if(has_member(members, "runtime_override_defaults"))
+    return;
+
+  ast_append(members, make_runtime_override_defaults(ast));
+}
+
+
 static void add_default_constructor(ast_t* ast)
 {
   pony_assert(ast != NULL);
@@ -182,6 +217,9 @@ static ast_result_t sugar_entity(pass_opt_t* opt, ast_t* ast, bool add_create,
 
   AST_GET_CHILDREN(ast, id, typeparams, defcap, traits, members);
 
+  if(ast_name(id) == stringtab("Main"))
+    add_default_runtime_override_defaults_method(ast);
+
   if(add_create)
     add_default_constructor(ast);
 

src/libponyc/type/subtype.c

@@ -1757,6 +1757,11 @@ bool is_env(ast_t* type)
   return is_literal(type, "Env");
 }
 
+bool is_runtime_options(ast_t* type)
+{
+  return is_literal(type, "RuntimeOptions");
+}
+
 bool is_bool(ast_t* type)
 {
   return is_literal(type, "Bool");

src/libponyc/type/subtype.h

@@ -37,6 +37,8 @@ bool is_none(ast_t* type);
 
 bool is_env(ast_t* type);
 
+bool is_runtime_options(ast_t* type);
+
 bool is_bool(ast_t* type);
 
 bool is_float(ast_t* type);

src/libponyc/verify/fun.c

@@ -1,8 +1,136 @@
 #include "fun.h"
+#include "../type/lookup.h"
 #include "../type/subtype.h"
 #include "ponyassert.h"
 #include <string.h>
 
+static bool verify_calls_runtime_override(pass_opt_t* opt, ast_t* ast)
+{
+  token_id tk = ast_id(ast);
+  if((tk == TK_NEWREF) || (tk == TK_NEWBEREF) ||
+     (tk == TK_FUNREF) || (tk == TK_BEREF))
+  {
+    ast_t* method = ast_sibling(ast_child(ast));
+    ast_t* receiver = ast_child(ast);
+
+    // Look up the original method definition for this method call.
+    deferred_reification_t* method_def = lookup(opt, ast, ast_type(receiver),
+      ast_name(method));
+    ast_t* method_ast = method_def->ast;
+
+    // The deferred reification doesn't own the underlying AST so we can free it
+    // safely.
+    deferred_reify_free(method_def);
+
+    if(ast_id(ast_parent(ast_parent(method_ast))) != TK_PRIMITIVE)
+    {
+      ast_error(opt->check.errors, ast,
+        "the runtime_override_defaults method of the Main actor can only call functions on primitives");
+      return false;
+    }
+    else
+    {
+      // recursively check function call tree for other non-primitive method calls
+      if(!verify_calls_runtime_override(opt, method_ast))
+        return false;
+    }
+  }
+
+  ast_t* child = ast_child(ast);
+
+  while(child != NULL)
+  {
+    // recursively check all child nodes for non-primitive method calls
+    if(!verify_calls_runtime_override(opt, child))
+      return false;
+
+    child = ast_sibling(child);
+  }
+  return true;
+}
+
+static bool verify_main_runtime_override_defaults(pass_opt_t* opt, ast_t* ast)
+{
+  if(ast_id(opt->check.frame->type) != TK_ACTOR)
+    return true;
+
+  ast_t* type_id = ast_child(opt->check.frame->type);
+
+  if(strcmp(ast_name(type_id), "Main"))
+    return true;
+
+  AST_GET_CHILDREN(ast, cap, id, typeparams, params, result, can_error, body);
+  ast_t* type = ast_parent(ast_parent(ast));
+
+  if(strcmp(ast_name(id), "runtime_override_defaults"))
+    return true;
+
+  bool ok = true;
+
+  if(ast_id(ast) != TK_FUN)
+  {
+    ast_error(opt->check.errors, ast,
+      "the runtime_override_defaults method of the Main actor must be a function");
+    ok = false;
+  }
+
+  if(ast_id(typeparams) != TK_NONE)
+  {
+    ast_error(opt->check.errors, typeparams,
+      "the runtime_override_defaults method of the Main actor must not take type parameters");
+    ok = false;
+  }
+
+  if(ast_childcount(params) != 1)
+  {
+    if(ast_pos(params) == ast_pos(type))
+      ast_error(opt->check.errors, params,
+        "The Main actor must have a runtime_override_defaults method which takes only a "
+        "single RuntimeOptions parameter");
+    else
+      ast_error(opt->check.errors, params,
+        "the runtime_override_defaults method of the Main actor must take only a single "
+        "RuntimeOptions parameter");
+    ok = false;
+  }
+
+  ast_t* param = ast_child(params);
+
+  if(param != NULL)
+  {
+    ast_t* p_type = ast_childidx(param, 1);
+
+    if(!is_runtime_options(p_type))
+    {
+      ast_error(opt->check.errors, p_type, "must be of type RuntimeOptions");
+      ok = false;
+    }
+  }
+
+  if(!is_none(result))
+  {
+    ast_error(opt->check.errors, result,
+      "the runtime_override_defaults method of the Main actor must return None");
+    ok = false;
+  }
+
+  bool bare = ast_id(cap) == TK_AT;
+
+  if(!bare)
+  {
+    ast_error(opt->check.errors, ast,
+      "the runtime_override_defaults method of the Main actor must be a bare function");
+    ok = false;
+  }
+
+  // check to make sure no function calls on non-primitives
+  if(!verify_calls_runtime_override(opt, body))
+  {
+    ok = false;
+  }
+
+  return ok;
+}
 
 static bool verify_main_create(pass_opt_t* opt, ast_t* ast)
 {
@@ -367,6 +495,7 @@ bool verify_fun(pass_opt_t* opt, ast_t* ast)
 
   // Run checks tailored to specific kinds of methods, if any apply.
   if(!verify_main_create(opt, ast) ||
+    !verify_main_runtime_override_defaults(opt, ast) ||
     !verify_primitive_init(opt, ast) ||
     !verify_any_final(opt, ast) ||
     !verify_any_serialise(opt, ast))

src/libponyrt/options/options.h

@@ -7,6 +7,10 @@
 #define OPT_ARG_OPTIONAL 1 << 1
 #define OPT_ARG_NONE     1 << 2
 #define OPT_ARGS_FINISH {NULL, 0, UINT32_MAX, UINT32_MAX}
+
+/* NOTE: if you change any of the argument help details, update the docstrings
+ *       in `RuntimeOptions` in the `builtin` package to keep them in sync.
+ */
 #define PONYRT_HELP \
   "Runtime options for Pony programs (not for use with ponyc):\n" \
   "  --ponymaxthreads Use N scheduler threads. Defaults to the number of\n" \
@@ -40,7 +44,10 @@
   "                   threads are pinned to CPUs. Requires `--ponypin` to\n" \
   "                   be set to have any effect.\n" \
   "  --ponyversion    Print the version of the compiler and exit.\n" \
-  "  --ponyhelp       Print the runtime usage options and exit.\n"
+  "  --ponyhelp       Print the runtime usage options and exit.\n" \
+  "\n" \
+  "NOTE: These can be programmatically overridden. See the docstring in the\n" \
+  "      `RuntimeOptions` struct in the `builtin` package.\n"
 
 typedef struct opt_arg_t
 {

src/libponyrt/sched/cpu.c

@@ -207,11 +207,11 @@ uint32_t ponyint_cpu_count()
 }
 
 uint32_t ponyint_cpu_assign(uint32_t count, scheduler_t* scheduler,
-  bool nopin, bool pinasio)
+  bool pin, bool pinasio)
 {
   uint32_t asio_cpu = -1;
 
-  if(nopin)
+  if(!pin)
   {
     for(uint32_t i = 0; i < count; i++)
     {