libvarnishapi-dev 5.2.1-1 / usr / include / varnish / vapi / vsm.h

/*-
 * Copyright (c) 2006 Verdens Gang AS
 * Copyright (c) 2006-2015 Varnish Software AS
 * All rights reserved.
 *
 * Author: Poul-Henning Kamp <phk@phk.freebsd.dk>
 * Author: Martin Blix Grydeland <martin@varnish-software.com>
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * This is the public API for the VSM access.
 *
 * The VSM "class" acts as parent class for the VSL and VSC subclasses.
 *
 */

#ifndef VAPI_VSM_H_INCLUDED
#define VAPI_VSM_H_INCLUDED

struct vsm;

/*
 * This structure is used to reference a VSM chunk
 */

struct vsm_fantom {
	uintptr_t		priv;		/* VSM private */
	struct VSM_chunk	*chunk;
	void			*b;		/* first byte of payload */
	void			*e;		/* first byte past payload */
	char			*class;
	char			*ident;
};

#define VSM_FANTOM_NULL { 0, 0, 0, 0, 0, 0 }

/*---------------------------------------------------------------------
 * VSM level access functions
 */

struct vsm *VSM_New(void);
	/*
	 * Allocate and initialize a VSL_data handle structure.
	 * This is the first thing you will always have to do.
	 * You can have multiple active vsm handles at the same time
	 * referencing the same or different shared memory files.
	 * Returns:
	 *	Pointer to usable VSL_data handle.
	 *	NULL: malloc failed.
	 */

void VSM_Destroy(struct vsm **vd);
	/*
	 * Close and deallocate all storage and mappings.
	 * (including any VSC and VSL "sub-classes" XXX?)
	 */

const char *VSM_Error(const struct vsm *vd);
	/*
	 * Return the first recorded error message.
	 */

void VSM_ResetError(struct vsm *vd);
	/*
	 * Reset recorded error message.
	 */

#define VSM_n_USAGE	"[-n varnish_name]"
#define VSM_t_USAGE	"[-t <seconds|off>]"

int VSM_Arg(struct vsm *, char flag, const char *arg);
	/*
	 * Handle all VSM specific command line arguments.
	 *
	 * Returns:
	 *	 1 on success
	 *	 <0 on failure, VSM_Error() returns diagnostic string
	 *
	 * 't' Configure patience during startup
	 *
	 *	If arg is "off", VSM_Attach() will wait forever.
	 *	Otherwise arg is the number of seconds to be patient
	 *	while the varnishd manager process gets started.
	 *
	 *	The default is five seconds.
	 *
	 * 'n' Configure varnishd instance to access
	 *
	 *	The default is the hostname.
	 */

int VSM_Attach(struct vsm *, int progress);
	/*
	 * Attach to the master process VSM segment, according to
	 * the 't' argument.  If `progress_fd` is non-negative, a
	 * period ('.') will be output for each second waited, and if
	 * any periods were output, a NL ('\n') is output before the
	 * function returns.
	 *
	 * Returns:
	 *	0	Attached
	 *	-1	Not Attached.
	 */

#define VSM_MGT_RUNNING		(1U<<1)
#define VSM_MGT_CHANGED		(1U<<2)
#define VSM_MGT_RESTARTED	(1U<<3)
#define VSM_WRK_RUNNING		(1U<<9)
#define VSM_WRK_CHANGED		(1U<<10)
#define VSM_WRK_RESTARTED	(1U<<11)

unsigned VSM_Status(struct vsm *);
	/*
	 * Returns a bitmap of the current status and changes in it
	 * since the previous call to VSM_Status
	 */

void VSM__iter0(const struct vsm *, struct vsm_fantom *vf);
int VSM__itern(struct vsm *, struct vsm_fantom *vf);

#define VSM_FOREACH(vf, vd) \
    for (VSM__iter0((vd), (vf)); VSM__itern((vd), (vf));)
	/*
	 * Iterate over all chunks in shared memory
	 * vf = "struct vsm_fantom *"
	 * vd = "struct vsm *"
	 */

int VSM_Map(struct vsm *, struct vsm_fantom *vf);
int VSM_Unmap(struct vsm *, struct vsm_fantom *vf);

struct vsm_valid {
	const char *name;
};

extern const struct vsm_valid VSM_invalid[];
extern const struct vsm_valid VSM_valid[];

const struct vsm_valid *VSM_StillValid(const struct vsm *, const struct vsm_fantom *vf);
	/*
	 * Check the validity of a previously looked up vsm_fantom.
	 *
	 * VSM_invalid means that the SHM chunk this fantom points to does
	 * not exist in the log file any longer.
	 *
	 * VSM_valid means that the SHM chunk this fantom points to is still
	 * good.
	 *
	 * Return:
	 *   VSM_invalid: fantom is not valid any more.
	 *   VSM_valid:   fantom is still the same.
	 */

int VSM_Get(struct vsm *, struct vsm_fantom *vf,
    const char *class, const char *ident);
	/*
	 * Find a chunk, produce fantom for it.
	 * Returns zero on failure.
	 * class is mandatory, ident optional.
	 */

char *VSM_Dup(struct vsm*, const char *class, const char *ident);
	/*
	 * Returns a malloc'ed copy of the fanton.
	 *
	 * Return:
	 *   NULL = Failure
	 *   !NULL = malloc'ed pointer
	 */

#endif /* VAPI_VSM_H_INCLUDED */