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.