.\" (C) 2023, NGINX, Inc.
.\"
.TH nxt_unit_init 3 (date) "NGINX Unit (unreleased)"
.SH Name
nxt_unit_init \- initialize Unit app
.SH Library
NGINX Unit library
.RI ( libunit ", " -lunit )
.SH Synopsis
.nf
.B #include <nxt_unit.h>
.PP
.B [[gnu::malloc(nxt_unit_done)]]
.BI "nxt_unit_ctx_t *_Nullable nxt_unit_init(nxt_unit_init_t *" init );
.fi
.SH Arguments
.TP
.I init
Object that specifies how the application should work.
.SH Description
.MR nxt_unit_init 3
initializes a Unit application.
.PP
It creates a main context object that
is necessary for most other libunit functions.
.PP
The next step after initializing the application is running it;
for that, see
.MR nxt_unit_run 3 .
.PP
The context object created by this function should be
destroyed by passing it to
.MR nxt_unit_done 3 .
.SH Return value
A pointer to a context object on success,
or NULL on error.
.SH Errors
Errors will be reported in the Unit debug log.
.IP \[bu] 3
.MR pthread_mutex_init 3
failed.
.PD 0
.IP \[bu]
.MR nxt_unit_malloc 3
failed.
.IP \[bu]
.I init->callbacks.request_handler
is NULL.
.PD
.SH Examples
.EX
#include <pthread.h>
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <strings.h>
#include <sys/types.h>
\&
#include <nxt_unit.h>
\&
// See \c
.MR nxt_unit_response_add_field 3 .
void request_handler(nxt_unit_request_info_t *req);
\&
// See \c
.MR nxt_unit_ctx_alloc 3 .
void *worker(void *main_ctx);
\&
static int ready_handler(nxt_unit_ctx_t *main_ctx);
\&
static ssize_t  nthreads;
static pthread_t  *threads;
\&
int
main(int argc, char **argv)
{
    int              err;
    void             *ret;
    nxt_unit_ctx_t   *ctx;
    nxt_unit_init_t  init;
\&
    if (argc == 3 && strcmp(argv[1], "\-t") == 0) {
        nthreads = atoi(argv[2]);
    }
\&
    bzero(&init, sizeof(nxt_unit_init_t));
    init.callbacks.request_handler = &request_handler;
    init.callbacks.ready_handler = &ready_handler;
\&
    ctx = nxt_unit_init(&init);
    if (ctx == NULL) {
        exit(EXIT_FAILURE);
    }
\&
    err = nxt_unit_run(ctx);
    nxt_unit_debug(ctx, "main worker finished with %d code", err);
\&
    for (ssize_t i = 0; i < nthreads; i++) {
        err = pthread_join(threads[i], &ret);
\&
        if (err != 0) {
            nxt_unit_alert(ctx, "pthread_join(#%zd) failed: %s (%d)",
                                i, strerror(err), err);
        } else {
            nxt_unit_debug(ctx, "pthread_join(#%zd) retval: %"PRIdPTR,
                                i, (intptr_t) ret);
        }
    }
\&
    nxt_unit_free(ctx, threads);
\&
    nxt_unit_done(ctx);
    nxt_unit_debug(NULL, "main worker done");
\&
    exit(EXIT_SUCCESS);
}
\&
static int
ready_handler(nxt_unit_ctx_t *ctx)
{
    int  err;
\&
    nxt_unit_debug(ctx, "ready");
\&
    if (nthreads <= 1) {
        return NXT_UNIT_OK;
    }
\&
    threads = nxt_unit_malloc(ctx, sizeof(pthread_t) * (nthreads \- 1));
    if (threads == NULL) {
        return NXT_UNIT_ERROR;
    }
\&
    // See \c
.MR nxt_unit_ctx_alloc 3 .
    for (ssize_t i = 0; i < nthreads \- 1; i++) {
        err = pthread_create(&threads[i], NULL, &worker, ctx);
        if (err != 0) {
            return NXT_UNIT_ERROR;
        }
    }
\&
    return NXT_UNIT_OK;
}
.EE
.SH Copyright
(C) 2017-2023, NGINX, Inc.
.PP
SPDX-License-Identifier: Apache-2.0
.SH See also
.MR nxt_unit_ctx_alloc 3 ,
.MR nxt_unit_run 3 ,
.MR nxt_unit_done 3 ,
.MR unitd 8
.PP
Website
.UR https://unit.nginx.org
.UE
.PP
Mailing list
.UR https://mailman.nginx.org/mailman/listinfo/unit
.UE
.PP
GitHub
.UR https://github.com/nginx/unit
.UE