Lightweight C library for HTML5 websockets
lws_context_creation_info Struct Reference

#include <lws-context-vhost.h>

Data Fields

gid_t gid
uid_t uid
uint64_t options
void * user
unsigned int count_threads
unsigned int fd_limit_per_thread
const char * vhost_name
void * external_baggage_free_on_destroy
unsigned int pt_serv_buf_size
void ** foreign_loops
void(* signal_cb )(void *event_lib_handle, int signum)
struct lws_context ** pcontext
void(* finalize )(struct lws_vhost *vh, void *arg)
void * finalize_arg
const char * listen_accept_role
const char * listen_accept_protocol
const struct lws_protocols ** pprotocols
const char * username
const char * groupname
const char * unix_socket_perms
const lws_system_ops_tsystem_ops
const lws_retry_bo_tretry_and_idle_policy
int rlimit_nofile
int fo_listen_queue
const struct lws_plugin_evlibevent_lib_custom
void * _unused [2]

Detailed Description

struct lws_context_creation_info - parameters to create context and /or vhost with

This is also used to create vhosts.... if LWS_SERVER_OPTION_EXPLICIT_VHOSTS is not given, then for backwards compatibility one vhost is created at context-creation time using the info from this struct.

If LWS_SERVER_OPTION_EXPLICIT_VHOSTS is given, then no vhosts are created at the same time as the context, they are expected to be created afterwards.

Field Documentation

◆ _unused

void* lws_context_creation_info::_unused[2]


◆ count_threads

unsigned int lws_context_creation_info::count_threads

CONTEXT: how many contexts to create in an array, 0 = 1

◆ event_lib_custom

const struct lws_plugin_evlib* lws_context_creation_info::event_lib_custom

CONTEXT: If non-NULL, override event library selection so it uses this custom event library implementation, instead of default internal loop. Don't set any other event lib context creation flags in that case. it will be used automatically. This is useful for integration where an existing application is using its own handrolled event loop instead of an event library, it provides a way to allow lws to use the custom event loop natively as if it were an "event library".

◆ external_baggage_free_on_destroy

void* lws_context_creation_info::external_baggage_free_on_destroy

CONTEXT: NULL, or pointer to something externally malloc'd, that should be freed when the context is destroyed. This allows you to automatically sync the freeing action to the context destruction action, so there is no need for an external free() if the context succeeded to create.

◆ fd_limit_per_thread

unsigned int lws_context_creation_info::fd_limit_per_thread

CONTEXT: nonzero means restrict each service thread to this many fds, 0 means the default which is divide the process fd limit by the number of threads.

Note if this is nonzero, and fd_limit_per_thread multiplied by the number of service threads is less than the process ulimit, then lws restricts internal lookup table allocation to the smaller size, and switches to a less efficient lookup scheme. You should use this to trade off speed against memory usage if you know the lws context will only use a handful of fds.

Bear in mind lws may use some fds internally, for example for the cancel pipe, so you may need to allow for some extras for normal operation.

◆ finalize

void(* lws_context_creation_info::finalize) (struct lws_vhost *vh, void *arg)

VHOST: NULL, or pointer to function that will be called back when the vhost is just about to be freed. The arg parameter will be set to whatever finalize_arg is below.

◆ finalize_arg

void* lws_context_creation_info::finalize_arg

VHOST: opaque pointer lws ignores but passes to the finalize callback. If you don't care, leave it NULL.

◆ fo_listen_queue

int lws_context_creation_info::fo_listen_queue

VHOST: 0 = no TCP_FASTOPEN, nonzero = enable TCP_FASTOPEN if the platform supports it, with the given queue length for the listen socket.

◆ foreign_loops

void** lws_context_creation_info::foreign_loops

CONTEXT: This is ignored if the context is not being started with an event loop, ie, .options has a flag like LWS_SERVER_OPTION_LIBUV.

NULL indicates lws should start its own even loop for each service thread, and deal with closing the loops when the context is destroyed.

Non-NULL means it points to an array of external ("foreign") event loops that are to be used in turn for each service thread. In the default case of 1 service thread, it can just point to one foreign event loop.

◆ gid

gid_t lws_context_creation_info::gid

CONTEXT: group id to change to after setting listen socket, or -1. See also .username below.

◆ groupname

const char* lws_context_creation_info::groupname

CONTEXT: string groupname for post-init permissions. Like .gid but takes a string groupname.

◆ listen_accept_protocol

const char* lws_context_creation_info::listen_accept_protocol

VHOST: NULL for default, or force accepted incoming connections to bind to this vhost protocol name.

◆ listen_accept_role

const char* lws_context_creation_info::listen_accept_role

VHOST: NULL for default, or force accepted incoming connections to bind to this role. Uses the role names from their ops struct, eg, "raw-skt".

◆ log_cx

lws_log_cx_t* lws_context_creation_info::log_cx

CONTEXT: NULL to use the default, process-scope logging context, else a specific logging context to associate with this context

◆ options

uint64_t lws_context_creation_info::options

VHOST + CONTEXT: 0, or LWS_SERVER_OPTION_... bitfields

◆ pcontext

struct lws_context** lws_context_creation_info::pcontext

CONTEXT: if non-NULL, at the end of context destroy processing, the pointer pointed to by pcontext is written with NULL. You can use this to let foreign event loops know that lws context destruction is fully completed.

◆ pprotocols

const struct lws_protocols** lws_context_creation_info::pprotocols

VHOST: NULL: use .protocols, otherwise ignore .protocols and use this array of pointers to protocols structs. The end of the array is marked by a NULL pointer.

This is preferred over .protocols, because it allows the protocol struct to be opaquely defined elsewhere, with just a pointer to it needed to create the context with it. .protocols requires also the type of the user data to be known so its size can be given.

◆ pt_serv_buf_size

unsigned int lws_context_creation_info::pt_serv_buf_size

CONTEXT: 0 = default of 4096. This buffer is used by various service related features including file serving, it defines the max chunk of file that can be sent at once. At the risk of lws having to buffer failed large sends, it can be increased to, eg, 128KiB to improve throughput.

◆ retry_and_idle_policy

const lws_retry_bo_t* lws_context_creation_info::retry_and_idle_policy

VHOST: optional retry and idle policy to apply to this vhost. Currently only the idle parts are applied to the connections.

◆ rlimit_nofile

int lws_context_creation_info::rlimit_nofile

0 = inherit the initial ulimit for files / sockets from the startup environment. Nonzero = try to set the limit for this process.

◆ signal_cb

void(* lws_context_creation_info::signal_cb) (void *event_lib_handle, int signum)

CONTEXT: NULL: default signal handling. Otherwise this receives the signal handler callback. event_lib_handle is the native event library signal handle, eg uv_signal_t * for libuv.

◆ system_ops

const lws_system_ops_t* lws_context_creation_info::system_ops

CONTEXT: hook up lws_system_ apis to system-specific implementations

◆ uid

uid_t lws_context_creation_info::uid

CONTEXT: user id to change to after setting listen socket, or -1. See also .groupname below.

◆ unix_socket_perms

const char* lws_context_creation_info::unix_socket_perms

VHOST: if your vhost is listening on a unix socket, you can give a "username:groupname" string here to control the owner:group it's created with. It's always created with 0660 mode.

◆ user

void* lws_context_creation_info::user

VHOST + CONTEXT: optional user pointer that will be associated with the context when creating the context (and can be retrieved by lws_context_user(context), or with the vhost when creating the vhost (and can be retrieved by lws_vhost_user(vhost)). You will need to use LWS_SERVER_OPTION_EXPLICIT_VHOSTS and create the vhost separately if you care about giving the context and vhost different user pointer values.

◆ username

const char* lws_context_creation_info::username

CONTEXT: string username for post-init permissions. Like .uid but takes a string username.

◆ vhost_name

const char* lws_context_creation_info::vhost_name

VHOST: name of vhost, must match external DNS name used to access the site, like "" as it's used to match Host: header and / or SNI name for SSL. CONTEXT: NULL, or the name to associate with the context for context-specific logging

The documentation for this struct was generated from the following file: