ark/include/soul_exports.h


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

#pragma once

/*
 * Single source of truth for the soul ABI.
 *
 * Consumers must define an X-macro like:
 *   #define X(ret, name, args) ...
 * and then invoke:
 *   ARKSOUL_EXPORTS(X)
 *
 * Note: this file intentionally does not include headers. Include whatever you
 * need (e.g. <stdint.h>, soul_types.h, wlroots headers) before expanding.
 */

#define ARKSOUL_EXPORTS(X)                                                    \
  /*                                                                           \
   * `arksoul_export_metaload`                                                 \
   *                                                                           \
   * Called at most once per process *per `soul_name`*. This is the place      \
   * for truly global initialization that should survive hot reloads (e.g.     \
   * one-time language runtime init, registering global hooks, etc.).          \
   *                                                                           \
   * Notes:                                                                    \
   * - May be a no-op.                                                         \
   * - Must be safe to call before any other soul entrypoint.                  \
   */                                                                          \
  X(void, arksoul_export_metaload, (int argc, char **argv))                    \
  /*                                                                           \
   * `arksoul_export_load`                                                     \
   *                                                                           \
   * Called every time the shared object is loaded (cold start and each hot    \
   * reload). Use this for per-load initialization that must be re-done after  \
   * `dlopen`.                                                                 \
   */                                                                          \
  X(void, arksoul_export_load, (int argc, char **argv))                        \
  /*                                                                           \
   * `arksoul_export_rebirth`                                                  \
   *                                                                           \
   * Called after a hot reload with the previous soul's preserved state.       \
   * Must return the new live opaque state (`opqst_t`) to be used for future   \
   * handler calls.                                                            \
   *                                                                           \
   * Contract:                                                                 \
   * - Must not fail hard on state incompatibility; fall back to a default.    \
   * - `self` is an opaque pointer owned by the runtime; treat it as           \
   * read-only.                                                                \
   */                                                                          \
  X(opqst_t, arksoul_export_rebirth,                                           \
    (void *self, uint8_t *marshalled_state, uint32_t n))                       \
  /*                                                                           \
   * `arksoul_export_ensoul`                                                   \
   *                                                                           \
   * Called on first boot when no previous state exists. Must construct and    \
   * return an initial opaque state.                                           \
   */                                                                          \
  X(opqst_t, arksoul_export_ensoul, (void *self))                              \
  /*                                                                           \
   * `arksoul_export_preserve`                                                 \
   *                                                                           \
   * Called before unloading the current soul during hot reload. Must          \
   * serialize the provided opaque state into a newly allocated byte buffer.   \
   *                                                                           \
   * Ownership:                                                                \
   * - Return a heap-allocated buffer (e.g. `malloc`).                         \
   * - The runtime takes ownership and will `free()` it after                  \
   * `arksoul_export_rebirth`.                                                 \
   */                                                                          \
  X(uint8_t *, arksoul_export_preserve, (opqst_t st, uint32_t *szout))         \
  /*                                                                           \
   * `arksoul_export_release`                                                  \
   *                                                                           \
   * Called immediately before the shared object is unloaded. Use this to      \
   * release resources owned by the opaque state (and any per-load resources   \
   * created in `arksoul_export_load`).                                        \
   */                                                                          \
  X(void, arksoul_export_release, (opqst_t st))                                \
  /*                                                                           \
   * `arksoul_export_handle_keybinding`                                        \
   *                                                                           \
   * Called for keyboard events. Returns the updated opaque state. Set         \
   * `*out_handled` to non-zero if the event is consumed.                      \
   */                                                                          \
  X(opqst_t, arksoul_export_handle_keybinding,                                 \
    (struct wlr_keyboard * keyboard, struct wlr_keyboard_key_event * event,    \
     uint32_t modifiers, uint32_t keysym, uint32_t codepoint,                  \
     int *out_handled, opqst_t state))                                         \
  /*                                                                           \
   * `arksoul_export_handle_button`                                            \
   *                                                                           \
   * Called for pointer button events (mouse/trackpad clicks). Returns the     \
   * updated opaque state.                                                     \
   */                                                                          \
  X(opqst_t, arksoul_export_handle_button,                                     \
    (struct wlr_pointer_button_event * event, uint32_t modifiers,              \
     opqst_t state))                                                           \
  /*                                                                           \
   * `arksoul_export_handle_motion`                                            \
   *                                                                           \
   * Called for pointer motion. Returns the updated opaque state.              \
   *                                                                           \
   * Parameters:                                                               \
   * - `event` is an opaque pointer to the underlying wlroots event struct     \
   *   (type depends on `is_absolute`).                                        \
   * - `lx`/`ly` are layout coordinates in compositor space.                   \
   */                                                                          \
  X(opqst_t, arksoul_export_handle_motion,                                     \
    (void *event, uint32_t modifiers, uint32_t is_absolute, double lx,         \
     double ly, opqst_t state))                                                \
  /*                                                                           \
   * `arksoul_export_handle_surface`                                           \
   *                                                                           \
   * Called when a surface is mapped/unmapped/destroyed. `surface` is an       \
   * opaque pointer to the runtime surface representation. Returns the updated \
   * opaque state.                                                             \
   */                                                                          \
  X(opqst_t, arksoul_export_handle_surface,                                    \
    (void *surface, surface_event_t event, opqst_t state))