<commit_before># Resource Model

[TOC]

The resource model for gVisor does not assume a fixed number of threads of
execution (i.e. vCPUs) or amount of physical memory. Where possible, decisions
about underlying physical resources are delegated to the host system, where
optimizations can be made with global information. This delegation allows the
sandbox to be highly dynamic in terms of resource usage: spanning a large number
of cores and large amount of memory when busy, and yielding those resources back
to the host when not.

In order words, the shape of the sandbox should closely track the shape of the
sandboxed process:

![Resource model](resources.png "Workloads of different shapes.")

## Processes

Much like a Virtual Machine (VM), a gVisor sandbox appears as an opaque process
on the system. Processes within the sandbox do not manifest as processes on the
host system, and process-level interactions within the sandbox require entering
the sandbox (e.g. via a [Docker exec][exec]).

## Networking

The sandbox attaches a network endpoint to the system, but runs its own network
stack. All network resources, other than packets in flight on the host, exist
only inside the sandbox, bound by relevant resource limits.

You can interact with network endpoints exposed by the sandbox, just as you
would any other container, but network introspection similarly requires entering
the sandbox.

## Files

Files in the sandbox may be backed by different implementations. For host-native
files (where a file descriptor is available), the Gofer may return a file
descriptor to the Sentry via [SCM_RIGHTS][scmrights][^1].

These files may be read from and written to through standard system calls, and
also mapped into the associated application's address space. This allows the
same host memory to be shared across multiple sandboxes, although this mechanism
does not preclude the use of side-channels (see [Security Model](./security.md).

Note that some file systems exist only within the context of the sandbox. For
example, in many cases a `tmpfs` mount will be available at `/tmp` or
`/dev/shm`, which allocates memory directly from the sandbox memory file (see
below). Ultimately, these will be accounted against relevant limits in a similar
way as the host native case.

## Threads

The Sentry models individual task threads with [goroutines][goroutine]. As a
result, each task thread is a lightweight [green thread][greenthread], and may
not correspond to an underlying host thread.

However, application execution is modelled as a blocking system call with the
Sentry. This means that additional host threads may be created, *depending on
the number of active application threads*. In practice, a busy application will
converge on the number of active threads, and the host will be able to make
scheduling decisions about all application threads.

## Time

Time in the sandbox is provided by the Sentry, through its own [vDSO][vdso] and
time-keeping implementation. This is distinct from the host time, and no state<commit_msg>typo: add missing ')' in doc<commit_after># Resource Model

[TOC]

The resource model for gVisor does not assume a fixed number of threads of
execution (i.e. vCPUs) or amount of physical memory. Where possible, decisions
about underlying physical resources are delegated to the host system, where
optimizations can be made with global information. This delegation allows the
sandbox to be highly dynamic in terms of resource usage: spanning a large number
of cores and large amount of memory when busy, and yielding those resources back
to the host when not.

In order words, the shape of the sandbox should closely track the shape of the
sandboxed process:

![Resource model](resources.png "Workloads of different shapes.")

## Processes

Much like a Virtual Machine (VM), a gVisor sandbox appears as an opaque process
on the system. Processes within the sandbox do not manifest as processes on the
host system, and process-level interactions within the sandbox require entering
the sandbox (e.g. via a [Docker exec][exec]).

## Networking

The sandbox attaches a network endpoint to the system, but runs its own network
stack. All network resources, other than packets in flight on the host, exist
only inside the sandbox, bound by relevant resource limits.

You can interact with network endpoints exposed by the sandbox, just as you
would any other container, but network introspection similarly requires entering
the sandbox.

## Files

Files in the sandbox may be backed by different implementations. For host-native
files (where a file descriptor is available), the Gofer may return a file
descriptor to the Sentry via [SCM_RIGHTS][scmrights][^1].

These files may be read from and written to through standard system calls, and
also mapped into the associated application's address space. This allows the
same host memory to be shared across multiple sandboxes, although this mechanism
does not preclude the use of side-channels (see [Security Model](./security.md)).

Note that some file systems exist only within the context of the sandbox. For
example, in many cases a `tmpfs` mount will be available at `/tmp` or
`/dev/shm`, which allocates memory directly from the sandbox memory file (see
below). Ultimately, these will be accounted against relevant limits in a similar
way as the host native case.

## Threads

The Sentry models individual task threads with [goroutines][goroutine]. As a
result, each task thread is a lightweight [green thread][greenthread], and may
not correspond to an underlying host thread.

However, application execution is modelled as a blocking system call with the
Sentry. This means that additional host threads may be created, *depending on
the number of active application threads*. In practice, a busy application will
converge on the number of active threads, and the host will be able to make
scheduling decisions about all application threads.

## Time

Time in the sandbox is provided by the Sentry, through its own [vDSO][vdso] and
time-keeping implementation. This is distinct from the host time, and no state
{'fraction_non_alphanumeric': 0.0450671910848902, 'fraction_numerical': 0.00032776138970829236, 'mean_word_length': 4.812380952380952, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4107878', 'n_tokens_mistral': 1487, 'n_tokens_neox': 1448, 'n_words': 929}