Region ownership

Data Structures
struct	lws_region_claim
struct	lws_region

Macros
#define	LWS_REGION_F_ABORT   (1 << 0) /* abort() on violation */

Typedefs
typedef struct lws_region_claim	lws_region_claim_t
typedef struct lws_region	lws_region_t

Enumerations
enum	{ LWS_REGION_NOT_TRACKED = -1 , LWS_REGION_E_OVERRUN = -2 , LWS_REGION_E_OVERLAP = -3 , LWS_REGION_E_FULL = -4 }

Functions
LWS_VISIBLE LWS_EXTERN int	lws_region_init (lws_region_t *r, const char *name, const void *base, size_t len, lws_region_claim_t *claims, size_t count_claims, unsigned int flags)
LWS_VISIBLE LWS_EXTERN int	lws_region_claim (lws_region_t *r, const void *p, size_t len, const char *who)
LWS_VISIBLE LWS_EXTERN void	lws_region_release (lws_region_t *r, int handle)
LWS_VISIBLE LWS_EXTERN void	lws_region_release_containing (lws_region_t *r, const void *p)
LWS_VISIBLE LWS_EXTERN void	lws_region_trim (lws_region_t *r, const void *p)
LWS_VISIBLE LWS_EXTERN int	lws_region_idle (const lws_region_t *r, const char *where)

Detailed Description

lws_region: who holds which range of a shared scratch buffer

A scratch buffer shared by several users, to avoid allocations, is only sound while each range of it has one user at a time. Ownership can be legitimately fragmented: a parser may still hold the unparsed tail of a read while a composer uses the already-consumed part below it.

lws_region makes that rule checkable. Each user claims the range it is about to use, with a name, and releases it when done. A claim that overlaps a live one fails naming both. A claim may give back its consumed prefix (lws_region_trim()), or be released by any pointer inside it (lws_region_release_containing()), which is how one user hands a buffer on to another without knowing its handle. lws_region_idle() confirms nothing is held, eg, at a point where the buffer's contents stop being meaningful.

Pointers outside the buffer are not tracked and are ignored by every call, so code that may be given either the shared buffer or some other storage can make the same calls regardless.

Nothing is allocated: the caller provides the lws_region_t and the table of claim slots, sized for how many claims may be live at once.

With LWS_REGION_F_ABORT, a violation is logged and then abort()s, so a debug build stops at the first one with both parties named; without it, the violation is logged and reported in the return code.

---

Data Structure Documentation

lws_region_claim

struct lws_region_claim

a claim slot: members are private to the lws_region_...() apis

Definition at line 55 of file lws-region.h.

Collaboration diagram for lws_region_claim:

Data Fields
const uint8_t *	s
const uint8_t *	e
const char *	who
uint16_t	gen

lws_region

struct lws_region

the tracked buffer: members are private to the lws_region_...() apis

Definition at line 63 of file lws-region.h.

Collaboration diagram for lws_region:

Data Fields
const char *	name
const uint8_t *	base
size_t	len
lws_region_claim_t *	claims
uint8_t	count_claims
uint8_t	flags

Macro Definition Documentation

LWS_REGION_F_ABORT

#define LWS_REGION_F_ABORT   (1 << 0) /* abort() on violation */

#include <lws-region.h>

Definition at line 73 of file lws-region.h.

Typedef Documentation

lws_region_claim_t

typedef struct lws_region_claim lws_region_claim_t

#include <lws-region.h>

a claim slot: members are private to the lws_region_...() apis

lws_region_t

typedef struct lws_region lws_region_t

#include <lws-region.h>

the tracked buffer: members are private to the lws_region_...() apis

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <lws-region.h>

Enumerator
LWS_REGION_NOT_TRACKED
LWS_REGION_E_OVERRUN
LWS_REGION_E_OVERLAP
LWS_REGION_E_FULL

Definition at line 76 of file lws-region.h.

     {
        LWS_REGION_NOT_TRACKED          = -1, /* p is not in the buffer */
        LWS_REGION_E_OVERRUN            = -2, /* runs past the end */
        LWS_REGION_E_OVERLAP            = -3, /* overlaps a live claim */
        LWS_REGION_E_FULL               = -4, /* no free claim slot */
};

Function Documentation

lws_region_init()

LWS_VISIBLE LWS_EXTERN int lws_region_init	(	lws_region_t *	r,
		const char *	name,
		const void *	base,
		size_t	len,
		lws_region_claim_t *	claims,
		size_t	count_claims,
		unsigned int	flags )

#include <lws-region.h>

lws_region_init() - start tracking claims on a buffer

Parameters

r	the region object to initialize
name	name of the buffer for logging, must outlive r
base	start of the buffer
len	length of the buffer
claims	caller-provided table of claim slots
count_claims	how many slots in claims, 1..255
flags	LWS_REGION_F_...

Returns 0, or -1 if count_claims is out of range. All slots start free.

References LWS_EXTERN, and LWS_VISIBLE.

lws_region_claim()

LWS_VISIBLE LWS_EXTERN int lws_region_claim	(	lws_region_t *	r,
		const void *	p,
		size_t	len,
		const char *	who )

#include <lws-region.h>

lws_region_claim() - claim len bytes at p for who

Parameters

r	the region
p	start of the range being claimed
len	length of the range
who	name of the claimant for logging, must outlive the claim

Returns a handle >= 0 for lws_region_release(), LWS_REGION_NOT_TRACKED if p is not inside the buffer (nothing is recorded, and releasing that result is a NOP), or an LWS_REGION_E_... error after logging it, if the flags did not have it abort instead.

References LWS_EXTERN, and LWS_VISIBLE.

lws_region_release()

LWS_VISIBLE LWS_EXTERN void lws_region_release	(	lws_region_t *	r,
		int	handle )

#include <lws-region.h>

lws_region_release() - release a claim by its handle

Parameters

r	the region
handle	what lws_region_claim() returned for it

Negative handles are ignored. So is a handle whose claim was already given up by lws_region_trim() or lws_region_release_containing(), even if the slot has since been reused by another claim.

References LWS_EXTERN, and LWS_VISIBLE.

lws_region_release_containing()

LWS_VISIBLE LWS_EXTERN void lws_region_release_containing	(	lws_region_t *	r,
		const void *	p )

#include <lws-region.h>

lws_region_release_containing() - release whichever claim covers p

Parameters

r	the region
p	any pointer inside the claim, inclusive of its end

For handing the buffer on without the claimant's handle. If p is not inside any live claim, it is a NOP.

References LWS_EXTERN, and LWS_VISIBLE.

lws_region_trim()

LWS_VISIBLE LWS_EXTERN void lws_region_trim	(	lws_region_t *	r,
		const void *	p )

#include <lws-region.h>

lws_region_trim() - give back the prefix of a claim below p

Parameters

r	the region
p	the new start of the claim covering p

The claim covering p then starts at p; if p is at its end, the claim is given up entirely. If p is not inside any live claim, it is a NOP.

References LWS_EXTERN, and LWS_VISIBLE.

lws_region_idle()

LWS_VISIBLE LWS_EXTERN int lws_region_idle	(	const lws_region_t *	r,
		const char *	where )

#include <lws-region.h>

lws_region_idle() - confirm nothing holds any of the buffer

Parameters

r	the region
where	name of the checkpoint for logging

Returns 0 if no claim is live, else logs the first live one and returns -1, if the flags did not have it abort instead.