7 System Services

Racket

7 System Services🔗ℹ

package: rivet

Generated native hosts call the first-party Swift/C++ system libraries directly; they do not install Racket procedures across the RVT1 boundary. Racket-side providers, headless tools, and tests may parameterize current-system-adapter with a deterministic adapter. The default adapter fails closed instead of silently pretending that an operating-system action succeeded.

struct
(struct system-adapter ( name
capabilities
acquire-single-instance
register-activation-handler
show-notification
set-tray-menu
set-autostart
autostart-enabled
secure-store-set
secure-store-ref
secure-store-remove
install-crash-hook))
  name : symbol?
  capabilities : list?
  acquire-single-instance : procedure?
  register-activation-handler : procedure?
  show-notification : procedure?
  set-tray-menu : procedure?
  set-autostart : procedure?
  autostart-enabled : procedure?
  secure-store-set : procedure?
  secure-store-ref : procedure?
  secure-store-remove : procedure?
  install-crash-hook : procedure?

Defines the operations supplied by a Racket-side provider or a test double. Native hosts expose equivalent platform APIs in their native system library.

parameter
(current-system-adapter) → system-adapter?
(current-system-adapter adapter) → void?
adapter : system-adapter?

The adapter used by all system-service convenience procedures.

procedure
(settings-store? value) → boolean?
value : any/c

Recognizes an opaque, synchronized JSON-backed preferences store. Its path, lock, and cached data are private so updates cannot bypass the atomic public operations. Transactions refresh under an in-process and operating-system lock, and returned JSON trees are deeply immutable.

parameter
(current-rivet-log-sink) → procedure?
(current-rivet-log-sink sink) → void?
sink : procedure?

Receives each structured log record. The default writes JSON to the current error port.

parameter
(current-rivet-crash-reporter) → procedure?
(current-rivet-crash-reporter reporter) → void?
reporter : procedure?

Receives a structured crash record and its exception. The default is a no-op.

procedure
(system-capabilities) → list?

Returns capability symbols advertised by the active adapter.

procedure
(acquire-single-instance! application-id
activation) → any/c
application-id : string?
activation : any/c

Acquires the application instance lock or forwards activation data to the existing instance, according to the native adapter.

procedure
(register-activation-handler! handler) → any/c
handler : procedure?

Registers the handler for deep links, file associations, and forwarded secondary-instance activation.

procedure
(show-system-notification! title
body
[ #:tag tag]) → any/c
  title : string?
  body : string?
  tag : (or/c #f string?) = #f

Displays an operating-system notification.

procedure
(set-tray-menu! items) → any/c
items : list?

Configures a platform tray or menu-bar menu.

procedure
(set-autostart! enabled?) → any/c
enabled? : boolean?

Enables or disables login startup.

procedure
(autostart-enabled?) → boolean?

Reports the current login-startup state.

procedure
(secure-store-set! service account secret) → any/c
  service : string?
  account : string?
  secret : bytes?

Stores a secret through the platform credential service.

procedure
(secure-store-ref service account [default]) → any/c
  service : string?
  account : string?
  default : any/c = #f

Reads a secret, returning default when no value is present.

procedure
(secure-store-remove! service account) → any/c
service : string?
account : string?

Removes a stored secret.

procedure
(install-crash-hook! handler) → any/c
handler : procedure?

Installs the platform-native crash handler. When the process fails, the handler receives a structured crash record; pair it with current-rivet-crash-reporter to route the Racket-side record the same way.

7.1 Settings and Diagnostics🔗ℹ

procedure
(make-settings-store path) → settings-store?
path : path-string?

Loads an atomic JSON-backed settings store.

procedure
(settings-ref store key [default]) → any/c
  store : settings-store?
  key : (or/c symbol? string?)
  default : any/c = #f

Reads a setting.

procedure
(settings-set! store key value) → any/c
  store : settings-store?
  key : (or/c symbol? string?)
  value : any/c

Persists a setting using atomic file replacement.

procedure
(settings-remove! store key) → void?
store : settings-store?
key : (or/c symbol? string?)

Removes a persisted setting.

procedure
(settings-snapshot store) → hash?
store : settings-store?

Returns the current immutable settings hash.

procedure
(rivet-log level event [#:fields fields]) → hash?
  level : (or/c 'debug 'info 'warning 'error 'critical)
  event : any/c
  fields : hash? = (hasheq)

Sends a structured record to current-rivet-log-sink and returns it.

procedure
(call-with-crash-reporting thunk
[ #:context context]) → any/c
thunk : (-> any/c)
context : hash? = (hasheq)

Reports an uncaught Racket exception through current-rivet-crash-reporter, then re-raises it.

1	Installation
2	Architecture and Module Boundaries
3	Finding and Integrating Missing Capabilities
4	Application Backend
5	Real-Time Chart Series
6	Application Identity
7	System Services
8	Distribution and Secure Updates
9	Command-Line Workflow
10	Further Reading