pw_multibuf

Overview

A buffer API optimized for zero-copy messaging.

Main docs: Home | Code size analysis

Submodules
	Experimental v2 API
	Experimental API that separates out the concern of memory allocation.
	Legacy v1 API
	Interfaces that will eventually be deprecated.

Macros
#define	PW_MULTIBUF_VERSION   1
#define	PW_MULTIBUF_WARN_DEPRECATED   0
#define	PW_MULTIBUF_DEPRECATED
#define	PW_MULTIBUF_INCLUDE_V1_ADAPTERS   1

Macro Definition Documentation

PW_MULTIBUF_INCLUDE_V1_ADAPTERS

#define PW_MULTIBUF_INCLUDE_V1_ADAPTERS   1

Includes v1_adapter for v2.

When true and PW_MULTIBUF_VERSION is 2, pw_multibuf will include adapter types that match the v1 API and wrap corresponding v2 types. These types facilitate migrating between versions. When project has migrated to v2, it can set this to 0 to verify that no code is still using the v1 API.

PW_MULTIBUF_VERSION

#define PW_MULTIBUF_VERSION   1

Sets the version of MultiBuf provided by this module.

This module is undergoing refactoring to improve usability and performance. Some portions of the version 1 API are in use by downstream consumers. These legacy interfaces are preserved for now, but deprecated.

Both versions are intended to minimize copying when working with sequences of memory buffers. These buffers are typically used to hold datagrams for use with I/O, and may be discontiguous.

Notable differences between the two versions include:

• V1 required the use of a MultiBufAllocator, whereas V2 defers memory allocation strategies to the consumer.
• V1 could provide views of higher level protocols be releasing and claiming prefixes and suffixes. V2 instead describes "layers" of span-like views of the underlying data.

Versions higher than 2 are currently unsupported.

Initially, this setting defaults to 1. Eventually, this will default to 2. Downstream projects may still use version 1 by overriding this configuration, but must be aware that version 1 will eventually be removed.

PW_MULTIBUF_WARN_DEPRECATED

#define PW_MULTIBUF_WARN_DEPRECATED   0

Enables warnings about using legacy MultiBuf.

This module is undergoing refactoring to improve usability and performance. Some portions of the version 1 API are in use by downstream consumers. These legacy interfaces are preserved for now, but deprecated.

Initially, this setting defaults to 0 and pw_multibuf.v1 may still be consumed without warning. At some point, this will default to 1. Downstream projects may still suppress the warning by overriding this configuration, but must be aware that legacy interfaces will eventually be removed.

See b/418013384 for background and details.