User Generator: composes synthetic user records. More...

#include <usergen.hpp>

Classes
struct	sources
	The library instances a user is drawn from. More...

Public Member Functions
	usg ()=default
	Default constructor — creates a generator with no account data, drawing from the singletons of the seven libraries.

	usg (sources from)
	A generator with no account data that draws from the given library instances (which must outlive it).

	usg (const usg &)=delete
	Not copyable.

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

	usg (usg &&) noexcept=default
	Movable.

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

	~usg ()=default
	Destructor.

user	get_user (const user_request &request)
	Generate a user with a new random seed.

user	get_user (const user_request &request, std::uint64_t call_seed) const
	Generate the user for a call seed. Deterministic; does not touch the generator's engine.

std::vector< user >	get_user_batch (const user_request &request, const core::batch_options &options)
	Generate a batch of users from a seed drawn like get_user() draws its own.

std::vector< user >	get_user_batch (const user_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of users, deterministically.

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

template<typename Sink >
void	for_each_user (const user_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of users with a batch seed drawn like get_user() draws its own.

std::vector< std::string >	supported_countries () const
	The countries a random user is drawn from.

bool	has_data () const
	Check whether the account data and every library has data.

bool	has_account_data () const
	Whether the account tables (platforms and statuses) are loaded.

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

bool	load (dataset tier)
	Load a dataset tier of the account data, replacing all account 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 (user_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 (user_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 (user_table which) const
	The layers in effect for one table, in order.

std::uint64_t	data_hash () const
	Hash of the loaded data: this generator's tables and the data of the seven libraries. Recorded in each result's signature(); a user with a device combines it with device-generator's.

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

Detailed Description

User Generator: composes synthetic user records.

A user is the identity core (a country, a birth, a name) and an online identity on top of it: a username, an email, a phone number, an address and an account with a password, sign-up and last-login times, a status, a platform and regional settings. The country is drawn once and passed to every part, so they agree. Each part gets its own call seed, split from the user's seed by name ("country", "birth", "name", "username", "email", "phone", "address", "password", "dates", "status", "platform", "locale", "timezone", "device"), so the user's seed replays all of it, and forcing one choice (a country, a status) does not shift the draws of the others. Output is identical on every compiler and platform (dasmig-core).

The generator composes the light libraries directly and does not use persona-generator: a user carries no body, traits, interests, job or city. It holds the data of the account only (platforms, statuses, locales and time zones); the rest comes from the instances of the seven libraries it was built on (the singletons by default), so their data, their layers and their lite or full tiers are the user's. A device, when a request asks for one, comes the same way from device-generator.

Thread safety: get_user(request, seed) is const and only calls const members of the libraries, so it may run concurrently. get_user(request) draws from the generator's engine and needs external synchronisation on the same instance; so do load() and extend().

Definition at line 326 of file usergen.hpp.

Constructor & Destructor Documentation

◆ usg()

dasmig::usg::usg ( sources from )

inlineexplicit

A generator with no account data that draws from the given library instances (which must outlive it).

Parameters

from	The instances to use.

Definition at line 349 of file usergen.hpp.

Member Function Documentation

◆ data_hash()

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

inline

Hash of the loaded data: this generator's tables and the data of the seven libraries. Recorded in each result's signature(); a user with a device combines it with device-generator's.

Returns: A hash that changes when any of them does; 0 when this generator's tables are empty.

Definition at line 669 of file usergen.hpp.

◆ extend() [1/2]

void dasmig::usg::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 user_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 600 of file usergen.hpp.

◆ extend() [2/2]

const core::layer_info & dasmig::usg::extend	(	user_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 633 of file usergen.hpp.

◆ extend_from_string()

const core::layer_info & dasmig::usg::extend_from_string	(	user_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 650 of file usergen.hpp.

◆ for_each_user() [1/2]

template<typename Sink >

void dasmig::usg::for_each_user	(	const user_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of users with a batch seed drawn like get_user() draws its own.

Template Parameters

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

Parameters

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

Definition at line 496 of file usergen.hpp.

◆ for_each_user() [2/2]

template<typename Sink >

void dasmig::usg::for_each_user	(	const user_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

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

Generates the same items as get_user_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, user&)`; 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 481 of file usergen.hpp.

◆ get_user() [1/2]

user dasmig::usg::get_user ( const user_request & request )

inline

Generate a user with a new random seed.

Parameters

request What to ask for; {} for the defaults.

Returns: The user; seed() replays it.

Exceptions

std::runtime_error	If this generator or a library has no data.
std::invalid_argument	If the request is invalid, or a country asked for is missing from a library.

Definition at line 377 of file usergen.hpp.

◆ get_user() [2/2]

user dasmig::usg::get_user	(	const user_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate the user for a call seed. Deterministic; does not touch the generator's engine.

Parameters

request	What to ask for.
call_seed	Any 64-bit seed.

Returns: The same user for the same seed, request and data.

Exceptions

std::runtime_error	If this generator or a library has no data.
std::invalid_argument	If the request is invalid, or a country asked for is missing from a library.

Definition at line 390 of file usergen.hpp.

◆ get_user_batch() [1/2]

std::vector< user > dasmig::usg::get_user_batch	(	const user_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of users from a seed drawn like get_user() draws its own.

Item i is get_user(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 437 of file usergen.hpp.

◆ get_user_batch() [2/2]

std::vector< user > dasmig::usg::get_user_batch	(	const user_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of users, deterministically.

Item i is exactly get_user(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 `user`, for example by `mail.address()`).
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 459 of file usergen.hpp.

◆ has_account_data()

bool dasmig::usg::has_account_data ( ) const

inline

Whether the account tables (platforms and statuses) are loaded.

Returns: True when both are non-empty.

Definition at line 538 of file usergen.hpp.

◆ has_data()

bool dasmig::usg::has_data ( ) const

inline

Check whether the account data and every library has data.

Returns: True when this generator can generate.

Definition at line 529 of file usergen.hpp.

◆ instance()

static usg & dasmig::usg::instance ( )

inlinestatic

Access the global singleton instance.

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

Returns: The singleton.

Definition at line 363 of file usergen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::usg::layers ( user_table which ) const

inline

The layers in effect for one table, in order.

Parameters

which The table.

Returns: The layer records.

Definition at line 659 of file usergen.hpp.

◆ load() [1/2]

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

inline

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

The directory must contain platforms.tsv and statuses.tsv; the other tables are read when present. A path without them is ignored. The libraries this one draws from are loaded on their own.

Parameters

dir	Directory such as `resources/lite`.

Exceptions

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

Definition at line 550 of file usergen.hpp.

◆ load() [2/2]

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

inline

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

Uses the compiled-in copy when the library is built with DASMIG_USER_EMBED, otherwise searches resources/, ../resources, user-generator/resources and ../user-generator/resources. The libraries this one draws from are loaded on their own.

Parameters

tier The tier.

Returns: False when the tier was not found.

Exceptions

core::tsv_error If a file is malformed.

Definition at line 573 of file usergen.hpp.

◆ supported_countries()

std::vector< std::string > dasmig::usg::supported_countries ( ) const

inline

The countries a random user is drawn from.

The countries for which the address, phone and email libraries and country-generator have data and name-generator has a culture. A country can be asked for by user_request::country outside this list only if the libraries do have it; one without names for a sex, or without a birth table, is refused when asked for and skipped when drawn.

Returns: ISO 3166-1 alpha-2 codes, sorted.

Definition at line 512 of file usergen.hpp.

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

dasmig/usergen.hpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ usg()

Member Function Documentation

◆ data_hash()

◆ extend() [1/2]

◆ extend() [2/2]

◆ extend_from_string()

◆ for_each_user() [1/2]

◆ for_each_user() [2/2]

◆ get_user() [1/2]

◆ get_user() [2/2]

◆ get_user_batch() [1/2]

◆ get_user_batch() [2/2]

◆ has_account_data()

◆ has_data()

◆ instance()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]

◆ supported_countries()