onload_set_stackname

Onload User Guide (UG1586)

Document ID
UG1586
Release Date
2023-07-31
Revision
1.2 English

Description

Select the Onload stack that new sockets are placed in. A socket can exist only in a single stack. A socket can be moved to a different stack - see onload_move_fd() below.

Moving a socket to a different stack does not create a copy of the socket in originator and target stacks.

Definition

int onload_set_stackname(int who, int scope, const char *name)

Formal Parameters

who
Must be one of the following:
  • ONLOAD_THIS_THREAD - to modify the stack name in which all subsequent sockets are created by this thread.
  • ONLOAD_ALL_THREADS - to modify the stack name in which all subsequent sockets are created by all threads in the current process. ONLOAD_THIS_THREAD takes precedence over ONLOAD_ALL_THREADS.
scope
Must be one of the following:
  • ONLOAD_SCOPE_THREAD - name is scoped with current thread
  • ONLOAD_SCOPE_PROCESS - name is scoped with current process
  • ONLOAD_SCOPE_USER - name is scoped with current user
  • ONLOAD_SCOPE_GLOBAL - name is global across all threads, users and processes.
  • ONLOAD_SCOPE_NOCHANGE - undo effect of a previous call to onload_set_stackname(ONLOAD_THIS_THREAD, …), see Note 4.
name
One of the following:
  • the stack name up to eight characters.
  • an empty string to set no stackname
  • the special value ONLOAD_DONT_ACCELERATE to prevent sockets created in this thread, user, process from being accelerated.

Sockets identified by the options above will belong to the Onload stack until a subsequent call using onload_set_stackname identifies a different stack or the ONLOAD_SCOPE_NOCHANGE option is used.

Return Value

0 on success

-1 with errno set to ENAMETOOLONG if the name exceeds permitted length

-1 with errno set to EINVAL if other parameters are invalid.

Note 1

This applies for stacks selected for sockets created by socket() and for pipe(), it has no effect on accept(). Passively opened sockets created via accept() will always be in the same stack as the listening socket that they are linked to. This means that the following are functionally identical:

onload_set_stackname(foo)
socket
listen
onload_set_stackname(bar)
accept

and:

onload_set_stackname(foo)
socket
listen
accept
onload_set_stackname(bar)

In both cases the listening socket and the accepted socket will be in stack foo.

Note 2

Scope defines the namespace in which a stack belongs. A stackname of foo in scope user is not the same as a stackname of foo in scope thread. Scope restricts the visibility of a stack to either the current thread, current process, current user or is unrestricted (global). This has the property that with, for example, process based scoping, two processes can have the same stackname without sharing a stack - as the stack for each process has a different namespace.

Note 3

Scoping can be thought of as adding a suffix to the supplied name, for example:

ONLOAD_SCOPE_THREAD: <stackname>-t<thread_id>

ONLOAD_SCOPE_PROCESS: <stackname>-p<process_id>

ONLOAD_SCOPE_USER: <stackname>-u<user_id>

ONLOAD_SCOPE_GLOBAL: <stackname>

This is an example only and the implementation is free to do something different such as maintaining different lists for different scopes.

Note 4

ONLOAD_SCOPE_NOCHANGE will undo the effect of a previous call to onload_set_stackname(ONLOAD_THIS_THREAD, …).

If you have previously used onload_set_stackname(ONLOAD_THIS_THREAD, …) and want to revert to the behavior of threads that are using the ONLOAD_ALL_THREADS configuration, without changing that configuration, you can do the following:

onload_set_stackname(ONLOAD_ALL_THREADS, ONLOAD_SCOPE_NOCHANGE, "");

Related Environment Variables

Related environment variables are:

EF_DONT_ACCELERATE

Default: 0

Minimum: 0

Maximum: 1

Scope: Per-process

If this environment variable is set then acceleration for ALL sockets is disabled and handed off to the kernel stack until the application overrides this state with a call to onload_set_stackname().

EF_STACK_PER_THREAD

Default: 0

Minimum: 0

Maximum: 1

Scope: Per-process

If this environment variable is set each socket created by the application will be placed in a stack depending on the thread in which it is created. Stacks could, for example, be named using the thread ID of the thread that creates the stack, but this should not be relied upon.

A call to onload_set_stackname overrides this variable. EF_DONT_ACCELERATE takes precedence over this variable.

EF_NAME

Default: none

Minimum: 0

Maximum: 8

Scope: Per-stack

The environment variable EF_NAME will be honored to control Onload stack sharing. However, a call to onload_set_stackname overrides this variable and, EF_DONT_ACCELERATE and EF_STACK_PER_THREAD both take precedence over EF_NAME.