xtc_app.h

/*-
 * Copyright (c) 2026, The XTC Project
 * Use of this source code is governed by the ISC License.
 *
 * src/inc/xtc_app.h
 *      The L4 application container: a root supervisor + a process
 *      registry + lifecycle plumbing.  Models OTP's `application`
 *      concept.  An xtc_app owns a loop (creating one if not given
 *      or borrowing one passed in), starts a top-level supervisor
 *      with the configured children, and exposes the registry that
 *      those children can use to find each other by name.
 *
 *      Typical usage:
 *
 *          xtc_app_t *app;
 *          xtc_app_opts_t opts = XTC_APP_OPTS_DEFAULT;
 *          xtc_app_create(&opts, &app);
 *          xtc_app_start(app, child_specs, n_children);
 *          xtc_app_run(app);              // blocks until app stops
 *          xtc_app_destroy(app);
 */
 
#ifndef XTC_APP_H
#define XTC_APP_H
 
#include "xtc_export.h"
 
#include <stddef.h>
 
#include "xtc.h"
#include "xtc_loop.h"
#include "xtc_exec.h"
#include "xtc_orc.h"
#include "xtc_reg.h"
 
typedef struct xtc_app xtc_app_t;
 
typedef struct xtc_app_opts {
        const char     *name;          /* optional, for logs */
        xtc_loop_t     *loop;          /* optional; NULL = create one */
        int             n_loops;       /* >1 = own an N-loop executor and run
                                        * the root supervisor on loop 0 (the
                                        * other loops host children placed via
                                        * xtc_child_spec.loop, and any work the
                                        * children spawn via xtc_app_exec); 0/1
                                        * = single loop.  Ignored when `loop`
                                        * is supplied. */
        xtc_sup_opts_t  sup;           /* root-supervisor settings */
        int             no_tuning_check; /* 1 = skip the __os_tuning_check()
                                        * power/kernel-tuning advisor probe
                                        * xtc_app_start runs by default
                                        * (PLAN.md 19.21); additive field,
                                        * appended last -- see
                                        * docs/abi-stability.md. */
} xtc_app_opts_t;
 
#define XTC_APP_OPTS_DEFAULT { \
        .name = NULL, \
        .loop = NULL, \
        .n_loops = 1, \
        .sup  = XTC_SUP_OPTS_DEFAULT, \
        .no_tuning_check = 0 \
}
 
/*
 * PUBLIC: int        xtc_app_create __P((const xtc_app_opts_t *, xtc_app_t **));
 * PUBLIC: void       xtc_app_destroy __P((xtc_app_t *));
 * PUBLIC: int        xtc_app_start __P((xtc_app_t *, const xtc_child_spec_t *, int));
 * PUBLIC: int        xtc_app_run __P((xtc_app_t *));
 * PUBLIC: int        xtc_app_stop __P((xtc_app_t *));
 * PUBLIC: xtc_loop_t *xtc_app_loop __P((const xtc_app_t *));
 * PUBLIC: xtc_exec_t *xtc_app_exec __P((const xtc_app_t *));
 * PUBLIC: xtc_reg_t  *xtc_app_registry __P((const xtc_app_t *));
 */
 
XTC_API int        xtc_app_create(const xtc_app_opts_t *opts, xtc_app_t **out);
XTC_API void       xtc_app_destroy(xtc_app_t *app);
 
/* Start the root supervisor with `n_children` initial children. */
XTC_API int        xtc_app_start(xtc_app_t *app,
                                 const xtc_child_spec_t *children,
                                 int n_children);
 
/* Run the loop until the supervisor exits or xtc_app_stop is called.
 * On return, xtc_app_destroy may be called. */
XTC_API int        xtc_app_run(xtc_app_t *app);
 
/* Asynchronously request the app to stop (kicks the root sup). */
XTC_API int        xtc_app_stop(xtc_app_t *app);
 
XTC_API xtc_loop_t *xtc_app_loop(const xtc_app_t *app);
 
/* The executor backing a multi-loop app (n_loops > 1), or NULL for a
 * single-loop app.  Children use it to spawn work across loops -- e.g.
 * a listener spawning a proc per connection round-robin. */
XTC_API xtc_exec_t *xtc_app_exec(const xtc_app_t *app);
 
XTC_API xtc_reg_t  *xtc_app_registry(const xtc_app_t *app);
 
#endif /* XTC_APP_H */