[ Table Of Contents | Keyword Index ]

Ns_Sls}(3) 4.99.2 "NaviServer Built-In Commands"

NAME

Ns_Sls} - Socket local storage

TABLE OF CONTENTS

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    FUNCTIONS
    ARGUMENTS
    EXAMPLES
    SEE ALSO
    KEYWORDS

SYNOPSIS

Ns_SlsAlloc sls cleanup
Ns_SlsSet sls sock data
Ns_SlsGet sls sock
Ns_SlsSetKeyed sock key value
Ns_SlsGetKeyed sock key

DESCRIPTION

The underlying TCP socket used by a NaviServer connection may be kept open and reused by following connections, e.g. during HTTP keep-alive . Using SLS you can save data with the socket, for the lifetime of the TCP connection.

There are two ways to save data: 1) by first allocating a slot you can save a pointer to arbitrary data; 2) using a string key you can save string data, which is also easily available via the Tcl ns_sls API.

The following functions require an active connection -- they should be called from e.g. a registered proc or filter.

FUNCTIONS

Ns_SlsAlloc sls cleanup
Allocate a new SLS slot. Must be called before the server completes startup.

Ns_SlsSet sls sock data
Save data in an SLS slot for the given connection socket. Any previously saved data for this slot will be freed using the registered cleanup function. The data will be freed automatically when the socket is closed.

Ns_SlsGet sls sock
Get the data associated with the given SLS slot and connection socket. If the slsPtr is invalid, the socket is invalid or closed, or no data has been saved in this slot then NULL is returned.

Ns_SlsSetKeyed sock key value
Copy the NUL terminated c-string value into SLS storage identified by key. The copied string will be automatically freed when the TCP socket closes, or when a new value is set with the same key. Data set using this API is available to Tcl code using the ns_sls get command.

Ns_SlsGetKeyed sock key
Returns a pointer to a NUL terminated c-string -- data previously saved via Ns_SlsSetKeyed or ns_sls set. NULL is returned if the connection socket is invalid, the key does not exist, or the saved data actually is NULL.

ARGUMENTS

Ns_Sls * sls (in/out)
An opaque SLS slot handle.

Ns_Sock * sock (in)
Pointer to the Ns_Sock structure associated with the current connection.

void * data (in)
The data to save in an SLS slot.

char * key (in)
Keye identifying string data.

char * value (in)
NUL terminated c-string value stored using the keyed data API. Memory is allocated and a copy is made. The value is also available via the ns_sls get command.

Ns_Callback * cleanup (in)
An optional callback function to free slot data. The original data will be passed as the callback argument.

EXAMPLES

Log the number of connections handled by a single TCP socket:

 
    #include "ns.h"

    typedef struct Data {
        int counter;
    } Data;

    static Ns_Callback   Cleanup;
    static Ns_FilterProc Filter;

    static Ns_Sls slot;

    int
    Ns_ModuleInit(CONST char *server, CONST char *module)
    {
        Ns_SlsAlloc(&slot, Cleanup);
        (void) Ns_RegisterFilter(server, "GET", "/*", Filter,
                                 NS_FILTER_PRE_AUTH, NULL);
    }

    static int
    Filter(void *arg, Ns_Conn *conn, int why)
    {
        Ns_Sock *sock = Ns_ConnSockPtr(conn);
        Ns_Sls  *slot;
        Data    *data;

        data = Ns_SlsGet(&slot, sock);
        if (!data) {
            data = ns_malloc(sizeof(Data));
            data->counter = 0;
            Ns_SlsSet(&slot, sock, data)
        }
        data->counter++;

        return NS_OK;
    }

    static int
    Cleanup(void *arg)
    {
        Data *data = arg;

        Ns_Log(Notice, "Example: sls counter: %d", data->counter);
        ns_free(data);
    }

SEE ALSO

Ns_Cls, Ns_Tls, ns_sls

KEYWORDS

Ns_SlsAlloc , Ns_SlsGet , Ns_SlsGetKeyed , Ns_SlsSet , Ns_SlsSetKeyed , data , sls , storage