onload_set_stackname

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.