Code Coverage: vinyl-cache/include/vapi/vsm.h
 
82217aa4fc7094b3610340078afaf78cd95a8ec9
 
0
/*-
1
 * Copyright (c) 2006 Verdens Gang AS
2
 * Copyright (c) 2006-2015 Varnish Software AS
3
 * All rights reserved.
4
 *
5
 * Author: Poul-Henning Kamp <phk@phk.freebsd.dk>
6
 * Author: Martin Blix Grydeland <martin@varnish-software.com>
7
 *
8
 * SPDX-License-Identifier: BSD-2-Clause
9
 *
10
 * Redistribution and use in source and binary forms, with or without
11
 * modification, are permitted provided that the following conditions
12
 * are met:
13
 * 1. Redistributions of source code must retain the above copyright
14
 *    notice, this list of conditions and the following disclaimer.
15
 * 2. Redistributions in binary form must reproduce the above copyright
16
 *    notice, this list of conditions and the following disclaimer in the
17
 *    documentation and/or other materials provided with the distribution.
18
 *
19
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
20
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22
 * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
23
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29
 * SUCH DAMAGE.
30
 *
31
 * This is the public API for the VSM access.
32
 *
33
 * The VSM category acts as parent category for the VSL and VSC sub-categories.
34
 *
35
 */
36
37
#ifndef VAPI_VSM_H_INCLUDED
38
#define VAPI_VSM_H_INCLUDED
39
40
struct vsm;
41
42
/*
43
 * This structure is used to reference a VSM chunk
44
 */
45
46
struct vsm_fantom {
47
        uintptr_t               priv;           /* VSM private */
48
        uintptr_t               priv2;          /* VSM private */
49
        void                    *b;             /* first byte of payload */
50
        void                    *e;             /* first byte past payload */
51
        char                    *category;
52
        char                    *ident;
53
};
54
55
#define VSM_FANTOM_NULL { 0, 0, 0, 0, 0, 0 }
56
57
/*---------------------------------------------------------------------
58
 * VSM level access functions
59
 */
60
61
struct vsm *VSM_New(void);
62
        /*
63
         * Allocate and initialize a VSL_data handle structure.
64
         * This is the first thing you will always have to do.
65
         * You can have multiple active vsm handles at the same time
66
         * referencing the same or different shared memory files.
67
         * Returns:
68
         *      Pointer to usable VSL_data handle.
69
         *      NULL: malloc failed.
70
         */
71
72
void VSM_Destroy(struct vsm **vd);
73
        /*
74
         * Close and deallocate all storage and mappings.
75
         * (including any VSC and VSL "sub-category" XXX?)
76
         */
77
78
const char *VSM_Error(const struct vsm *vd);
79
        /*
80
         * Return the first recorded error message.
81
         */
82
83
void VSM_ResetError(struct vsm *vd);
84
        /*
85
         * Reset recorded error message.
86
         */
87
88
#define VSM_n_USAGE     "[-n vinyl_name]"
89
#define VSM_t_USAGE     "[-t <seconds|off>]"
90
91
int VSM_Arg(struct vsm *, char flag, const char *arg);
92
        /*
93
         * Handle all VSM specific command line arguments.
94
         *
95
         * Returns:
96
         *       1 on success
97
         *       <0 on failure, VSM_Error() returns diagnostic string
98
         *
99
         * 't' Configure patience during startup
100
         *
101
         *      If arg is "off", VSM_Attach() will wait forever.
102
         *      Otherwise arg is the number of seconds to be patient
103
         *      while the vinyld manager process gets started.
104
         *
105
         *      The default is five seconds.
106
         *
107
         * 'n' Configure vinyld instance to access
108
         *
109
         *      The default is the hostname.
110
         */
111
112
int VSM_Attach(struct vsm *, int progress);
113
        /*
114
         * Attach to the master process VSM segment, according to
115
         * the 't' argument.  If `progress_fd` is non-negative, a
116
         * period ('.') will be output for each second waited, and if
117
         * any periods were output, a NL ('\n') is output before the
118
         * function returns.
119
         *
120
         * Returns:
121
         *      0       Attached
122
         *      -1      Not Attached.
123
         */
124
125 52151
#define VSM_MGT_RUNNING         (1U<<1)
126 5054
#define VSM_MGT_CHANGED         (1U<<2)
127 47935
#define VSM_MGT_RESTARTED       (1U<<3)
128 28498
#define VSM_WRK_RUNNING         (1U<<9)
129 30974
#define VSM_WRK_CHANGED         (1U<<10)
130 49201
#define VSM_WRK_RESTARTED       (1U<<11)
131
132
#define VSM_MGT_MASK 0x00ff
133 25920
#define VSM_WRK_MASK 0xff00
134
135
unsigned VSM_Status(struct vsm *);
136
        /*
137
         * Returns a bitmap of the current status and changes in it
138
         * since the previous call to VSM_Status
139
         */
140
141
void VSM__iter0(const struct vsm *, struct vsm_fantom *vf);
142
int VSM__itern(struct vsm *, struct vsm_fantom *vf);
143
144
#define VSM_FOREACH(vf, vd) \
145 125871
    for (VSM__iter0((vd), (vf)); VSM__itern((vd), (vf));)
146
        /*
147
         * Iterate over all chunks in shared memory
148
         * vf = "struct vsm_fantom *"
149
         * vd = "struct vsm *"
150
         */
151
152
int VSM_Map(struct vsm *, struct vsm_fantom *vf);
153
int VSM_Unmap(struct vsm *, struct vsm_fantom *vf);
154
155
struct vsm_valid {
156
        const char *name;
157
};
158
159
extern const struct vsm_valid VSM_invalid[];
160
extern const struct vsm_valid VSM_valid[];
161
162
const struct vsm_valid *VSM_StillValid(const struct vsm *, const struct vsm_fantom *vf);
163
        /*
164
         * Check the validity of a previously looked up vsm_fantom.
165
         *
166
         * VSM_invalid means that the SHM chunk this fantom points to does
167
         * not exist in the log file any longer.
168
         *
169
         * VSM_valid means that the SHM chunk this fantom points to is still
170
         * good.
171
         *
172
         * Return:
173
         *   VSM_invalid: fantom is not valid anymore.
174
         *   VSM_valid:   fantom is still the same.
175
         */
176
177
int VSM_Get(struct vsm *, struct vsm_fantom *vf,
178
    const char *category, const char *ident);
179
        /*
180
         * Find a chunk, produce fantom for it.
181
         * Returns zero on failure.
182
         * category is mandatory, ident optional.
183
         */
184
185
char *VSM_Dup(struct vsm*, const char *category, const char *ident);
186
        /*
187
         * Returns a malloc'ed copy of the fantom.
188
         *
189
         * Return:
190
         *   NULL = Failure
191
         *   !NULL = malloc'ed pointer
192
         */
193
194
#endif /* VAPI_VSM_H_INCLUDED */