Device Generator: devices whose model, OS, browser, user agent, screen and IP address fit together at a date. More...

#include <devicegen.hpp>

Public Member Functions
	dvg ()=default
	Default constructor — creates an empty generator with no data.

	dvg (const dvg &)=delete
	Not copyable.

dvg &	operator= (const dvg &)=delete
	Not copyable.

	dvg (dvg &&) noexcept=default
	Movable.

dvg &	operator= (dvg &&) noexcept=default
	Movable.

	~dvg ()=default
	Destructor.

device	get_device (const device_request &request)
	Generate a random device. Use device_request{} for the defaults.

device	get_device (const device_request &request, std::uint64_t call_seed) const
	Generate a deterministic device.

std::vector< device >	get_device_batch (const device_request &request, const core::batch_options &options)
	Generate a batch of devices from a seed drawn like get_device() draws its own.

std::vector< device >	get_device_batch (const device_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of devices, deterministically.

template<typename Sink >
void	for_each_device (const device_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of devices to a sink without holding the whole batch.

template<typename Sink >
void	for_each_device (const device_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of devices with a batch seed drawn like get_device() draws its own.

std::vector< std::string >	countries () const
	The countries a request can name: those with a row in `countries.tsv`, sorted.

std::vector< std::string >	platforms () const
	The platform keys a request can name, in table order.

std::size_t	country_count () const
	The number of countries loaded.

std::size_t	model_count () const
	The number of device models loaded.

bool	has_data () const
	Check whether the data needed to generate is loaded.

void	load (const std::filesystem::path &dir)
	Load data from a resource directory, replacing all data and layers loaded before.

bool	load (dataset tier)
	Load a dataset tier, replacing all data and layers loaded before.

void	extend (const std::filesystem::path &path, core::layer_mode mode=core::layer_mode::override)
	Add data layers from a directory or a file.

const core::layer_info &	extend (device_table which, core::tsv_document doc, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table.

const core::layer_info &	extend_from_string (device_table which, std::string_view text, std::string source, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table from TSV text (for example from a WebAssembly host).

const std::vector< core::layer_info > &	layers (device_table which) const
	The layers in effect for one table, in order.

std::uint64_t	data_hash () const
	Hash of the loaded data, recorded in each result's signature().

Static Public Member Functions
static dvg &	instance ()
	Access the global singleton instance.

Detailed Description

Device Generator: devices whose model, OS, browser, user agent, screen and IP address fit together at a date.

A call draws, from streams split from the call seed: the country ("country"), the platform ("platform"), the maker and model ("model"), the OS version ("os-version"), the browser ("browser") and its version ("browser-version"), the screen ("screen"), the IP family ("ip-version") and the address ("ip"). Fixing one in the request leaves the others' draws unchanged. Output is identical on every compiler and platform (dasmig-core).

Can be used as a singleton via instance() or constructed independently.

Thread safety: Each instance is independent. Concurrent calls to get_device(request) on the same instance require external synchronisation; the seeded overload is const and safe to call concurrently.

Definition at line 308 of file devicegen.hpp.

Member Function Documentation

◆ countries()

std::vector< std::string > dasmig::dvg::countries ( ) const

inline

The countries a request can name: those with a row in countries.tsv, sorted.

Returns: ISO 3166-1 alpha-2 codes.

Definition at line 481 of file devicegen.hpp.

◆ country_count()

std::size_t dasmig::dvg::country_count ( ) const

inline

The number of countries loaded.

Returns: The count.

Definition at line 501 of file devicegen.hpp.

◆ data_hash()

std::uint64_t dasmig::dvg::data_hash ( ) const

inline

Hash of the loaded data, recorded in each result's signature().

Returns: A hash that changes when any table does; 0 when nothing is loaded.

Definition at line 637 of file devicegen.hpp.

◆ extend() [1/2]

void dasmig::dvg::extend	(	const std::filesystem::path &	path,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add data layers from a directory or a file.

A directory may hold any of the table files (see device_table); all are applied together or, if any fails, none. A file must have one of those names.

Parameters

path	Directory or file.
mode	How the layers combine with the data loaded before.

Exceptions

core::tsv_error	If a file cannot be read or a row is invalid; the data is then unchanged.
std::invalid_argument	If `path` is a file with another name.

Definition at line 571 of file devicegen.hpp.

◆ extend() [2/2]

const core::layer_info & dasmig::dvg::extend	(	device_table	which,
		core::tsv_document	doc,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add a data layer to one table.

Rows are keyed by the table's key columns (see doc/data.md). In the default override mode a row replaces the loaded row with the same key and new keys are added; a row with disabled set to 1 removes its key.

Parameters

which	The table.
doc	TSV with that table's columns.
mode	How the layer combines with the data loaded before.

Returns: What the layer did (rows added, replaced, removed, warnings).

Exceptions

core::tsv_error If a row is invalid; the data is unchanged.

Definition at line 603 of file devicegen.hpp.

◆ extend_from_string()

const core::layer_info & dasmig::dvg::extend_from_string	(	device_table	which,
		std::string_view	text,
		std::string	source,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add a data layer to one table from TSV text (for example from a WebAssembly host).

Parameters

which	The table.
text	TSV with that table's columns.
source	Name used in errors.
mode	How the layer combines with the data loaded before.

Returns: What the layer did.

Exceptions

core::tsv_error If a row is invalid; the data is unchanged.

Definition at line 620 of file devicegen.hpp.

◆ for_each_device() [1/2]

template<typename Sink >

void dasmig::dvg::for_each_device	(	const device_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of devices with a batch seed drawn like get_device() draws its own.

Template Parameters

Sink	Callable taking `(std::uint64_t, device&)`.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
sink	Receives the items.

Definition at line 471 of file devicegen.hpp.

◆ for_each_device() [2/2]

template<typename Sink >

void dasmig::dvg::for_each_device	(	const device_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

Stream a batch of devices to a sink without holding the whole batch.

Generates the same items as get_device_batch() and calls sink(index, item) in index order on the calling thread; index includes options.first.

Template Parameters

Sink	Callable taking `(std::uint64_t, device&)`; for example core::jsonl_writer or core::csv_writer.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
batch_seed	Seed of the whole batch.
sink	Receives the items.

Definition at line 456 of file devicegen.hpp.

◆ get_device() [1/2]

device dasmig::dvg::get_device ( const device_request & request )

inline

Generate a random device. Use device_request{} for the defaults.

Parameters

request What to generate.

Returns: The device.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the request is invalid (see the seeded overload).

Definition at line 340 of file devicegen.hpp.

◆ get_device() [2/2]

device dasmig::dvg::get_device	(	const device_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic device.

Parameters

request	What to generate.
call_seed	Seed; the same request, seed and data give the same result. Does not touch the instance engine.

Returns: The device.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the reference date is before device_request::earliest_reference_date or not a valid date, the country, platform or browser is unknown, the kind contradicts the platform, the browser does not run on the platform, the country has no registered addresses (unless `safe`), or the locale is not a BCP 47 tag.

Definition at line 354 of file devicegen.hpp.

◆ get_device_batch() [1/2]

std::vector< device > dasmig::dvg::get_device_batch	(	const device_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of devices from a seed drawn like get_device() draws its own.

Item i is get_device(request, core::item_seed(batch_seed, options.first + i)) for the drawn batch seed; see the seeded overload.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.

Returns: The results, in index order.

Definition at line 412 of file devicegen.hpp.

◆ get_device_batch() [2/2]

std::vector< device > dasmig::dvg::get_device_batch	(	const device_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of devices, deterministically.

Item i is exactly get_device(request, core::item_seed(batch_seed, options.first + i)), so an item replays on its own, a range can be generated directly, two batches that follow each other equal one, and the output does not depend on options.threads.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (see core::unique_rule; the rule must be made for `device`, for example keyed by the IP).
batch_seed	Seed of the whole batch.

Returns: The results, in index order.

Exceptions

std::invalid_argument	If the request or options are invalid.
std::runtime_error	If no data has been loaded, or a unique batch runs out of attempts.

Definition at line 434 of file devicegen.hpp.

◆ has_data()

bool dasmig::dvg::has_data ( ) const

inline

Check whether the data needed to generate is loaded.

Returns: True when countries and platforms are loaded.

Definition at line 511 of file devicegen.hpp.

◆ instance()

static dvg & dasmig::dvg::instance ( )

inlinestatic

Access the global singleton instance.

Loads the lite tier (or full if lite is missing) on first access, from compiled-in data or an auto-probed resources/.

Returns: The singleton.

Definition at line 325 of file devicegen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::dvg::layers ( device_table which ) const

inline

The layers in effect for one table, in order.

Parameters

which The table.

Returns: The layer records.

Definition at line 629 of file devicegen.hpp.

◆ load() [1/2]

void dasmig::dvg::load ( const std::filesystem::path & dir )

inline

Load data from a resource directory, replacing all data and layers loaded before.

The directory must contain countries.tsv and platforms.tsv; the other tables are read when present. A path without them is ignored.

Parameters

dir	Directory such as `resources/lite`.

Exceptions

core::tsv_error If a file is malformed; the data is then unchanged.

Definition at line 522 of file devicegen.hpp.

◆ load() [2/2]

bool dasmig::dvg::load ( dataset tier )

inline

Load a dataset tier, replacing all data and layers loaded before.

Uses the compiled-in copy when the library is built with DASMIG_DEVICE_EMBED, otherwise searches resources/, ../resources, device-generator/resources and ../device-generator/resources.

Parameters

tier The tier.

Returns: False when the tier was not found.

Exceptions

core::tsv_error If a file is malformed.

Definition at line 544 of file devicegen.hpp.

◆ model_count()

std::size_t dasmig::dvg::model_count ( ) const

inline

The number of device models loaded.

Returns: The count.

Definition at line 505 of file devicegen.hpp.

◆ platforms()

std::vector< std::string > dasmig::dvg::platforms ( ) const

inline

The platform keys a request can name, in table order.

Returns: The keys.

Definition at line 491 of file devicegen.hpp.

The documentation for this class was generated from the following file:

dasmig/devicegen.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ countries()

◆ country_count()

◆ data_hash()

◆ extend() [1/2]

◆ extend() [2/2]

◆ extend_from_string()

◆ for_each_device() [1/2]

◆ for_each_device() [2/2]

◆ get_device() [1/2]

◆ get_device() [2/2]

◆ get_device_batch() [1/2]

◆ get_device_batch() [2/2]

◆ has_data()

◆ instance()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]

◆ model_count()

◆ platforms()