The loop class. More...

#include <loop.h>

Inheritance diagram for uvw::loop:

Collaboration diagram for uvw::loop:

Public Member Functions
template<typename... Args>
int	configure (option flag, Args &&...args)
	Sets additional loop options.

template<typename R , typename... Args>
std::shared_ptr< R >	resource (Args &&...args)
	Creates resources of any type.

template<typename R , typename... Args>
std::shared_ptr< R >	uninitialized_resource (Args &&...args)
	Creates uninitialized resources of any type.

int	close ()
	Releases all internal loop resources.

int	run (run_mode mode=run_mode::DEFAULT) noexcept
	Runs the event loop.

bool	alive () const noexcept
	Checks if there are active resources.

void	stop () noexcept
	Stops the event loop.

int	descriptor () const noexcept
	Get backend file descriptor.

std::pair< bool, time >	timeout () const noexcept
	Gets the poll timeout.

time	idle_time () const noexcept
	Returns the amount of time the event loop has been idle. The call is thread safe.

metrics_type	metrics () const noexcept
	Tracks various internal operations of the event loop.

time	now () const noexcept
	Returns the current timestamp in milliseconds.

void	update () const noexcept
	Updates the event loop’s concept of now.

template<typename Func >
void	walk (Func callback)
	Walks the list of handles.

int	fork () noexcept
	Reinitialize any kernel state necessary in the child process after a fork(2) system call.

template<typename R = void>
std::shared_ptr< R >	data () const
	Gets user-defined data. `uvw` won't use this field in any case.

void	data (std::shared_ptr< void > ud)
	Sets arbitrary data. `uvw` won't use this field in any case.

const uv_loop_t *	raw () const noexcept
	Gets the underlying raw data structure.

uv_loop_t *	raw () noexcept
	Gets the underlying raw data structure.

Public Member Functions inherited from uvw::emitter< loop >
void	on (listener_t< U > f)
	Registers a long-lived listener with the event emitter.

void	reset () noexcept
	Disconnects the listener for the given event type.

void	reset () noexcept
	Disconnects all listeners.

bool	has () const noexcept
	Checks if there is a listener registered for the specific event.

Static Public Member Functions
static std::shared_ptr< loop >	create ()
	Initializes a new loop instance.

static std::shared_ptr< loop >	create (uv_loop_t *res)
	Initializes a new loop instance from an existing resource.

static std::shared_ptr< loop >	get_default ()
	Gets the initialized default loop.

Detailed Description

The loop class.

The event loop is the central part of uvw's functionalities, as well as libuv's ones.
It takes care of polling for I/O and scheduling callbacks to be run based on different sources of events.

Definition at line 60 of file loop.h.

Member Function Documentation

◆ alive()

bool uvw::loop::alive ( ) const

noexcept

Checks if there are active resources.

Returns: True if there are active resources in the loop.

◆ close()

int uvw::loop::close ( )

Releases all internal loop resources.

Call this function only when the loop has finished executing and all open handles and requests have been closed, or the loop will error.

Returns: Underlying return value.

◆ configure()

template<typename... Args>

int uvw::loop::configure	(	option	flag,
		Args &&...	args
	)

inline

Sets additional loop options.

You should normally call this before the first call to uv_run() unless mentioned otherwise.
Supported options:

loop::option::BLOCK_SIGNAL: Block a signal when polling for new events. A second argument is required and it is the signal number.
loop::option::IDLE_TIME: Accumulate the amount of idle time the event loop spends in the event provider. This option is necessary to use idle_time().

See the official documentation for further details.

Returns: Underlying return value.

Definition at line 139 of file loop.h.

◆ create() [1/2]

static std::shared_ptr< loop > uvw::loop::create ( )

static

Initializes a new loop instance.

Returns: A pointer to the newly created loop.

◆ create() [2/2]

static std::shared_ptr< loop > uvw::loop::create ( uv_loop_t * res )

static

Initializes a new loop instance from an existing resource.

The lifetime of the resource must exceed that of the instance to which it's associated. Management of the memory associated with the resource is in charge of the user.

Parameters

res	A valid pointer to a correctly initialized resource.

Returns: A pointer to the newly created loop.

◆ data() [1/2]

template<typename R = void>

std::shared_ptr< R > uvw::loop::data ( ) const

inline

Gets user-defined data. uvw won't use this field in any case.

Returns: User-defined data if any, an invalid pointer otherwise.

Definition at line 375 of file loop.h.

◆ data() [2/2]

void uvw::loop::data ( std::shared_ptr< void > ud )

Sets arbitrary data. uvw won't use this field in any case.

Parameters

ud	User-defined arbitrary data.

◆ descriptor()

int uvw::loop::descriptor ( ) const

noexcept

Get backend file descriptor.

Only kqueue, epoll and event ports are supported.
This can be used in conjunction with run(loop::run_mode::NOWAIT) to poll in one thread and run the event loop’s callbacks in another.

Returns: The backend file descriptor.

◆ fork()

int uvw::loop::fork ( )

noexcept

Reinitialize any kernel state necessary in the child process after a fork(2) system call.

Previously started watchers will continue to be started in the child process.

It is necessary to explicitly call this function on every event loop created in the parent process that you plan to continue to use in the child, including the default loop (even if you don’t continue to use it in the parent). This function must be called before calling any API function using the loop in the child. Failure to do so will result in undefined behaviour, possibly including duplicate events delivered to both parent and child or aborting the child process.

When possible, it is preferred to create a new loop in the child process instead of reusing a loop created in the parent. New loops created in the child process after the fork should not use this function.

Note that this function is not implemented on Windows.
Note also that this function is experimental in libuv. It may contain bugs, and is subject to change or removal. API and ABI stability is not guaranteed.

See the official documentation for further details.

Returns: Underlying return value.

◆ get_default()

static std::shared_ptr< loop > uvw::loop::get_default ( )

static

Gets the initialized default loop.

It may return an empty pointer in case of failure.
This function is just a convenient way for having a global loop throughout an application, the default loop is in no way different than the ones initialized with create().
As such, the default loop can be closed with close() so the resources associated with it are freed (even if it is not strictly necessary).

Returns: The initialized default loop.

◆ idle_time()

time uvw::loop::idle_time ( ) const

noexcept

Returns the amount of time the event loop has been idle. The call is thread safe.

Returns: The accumulated time spent idle.

◆ metrics()

metrics_type uvw::loop::metrics ( ) const

noexcept

Tracks various internal operations of the event loop.

Returns: Event loop metrics.

◆ now()

time uvw::loop::now ( ) const

noexcept

Returns the current timestamp in milliseconds.

The timestamp is cached at the start of the event loop tick.
The timestamp increases monotonically from some arbitrary point in time.
Don’t make assumptions about the starting point, you will only get disappointed.

Returns: The current timestamp in milliseconds (actual type is std::chrono::duration<uint64_t, std::milli>).

◆ raw() [1/2]

const uv_loop_t * uvw::loop::raw ( ) const

noexcept

Gets the underlying raw data structure.

This function should not be used, unless you know exactly what you are doing and what are the risks.
Going raw is dangerous, mainly because the lifetime management of a loop, a handle or a request is in charge to the library itself and users should not work around it.

Warning: Use this function at your own risk, but do not expect any support in case of bugs.

Returns: The underlying raw data structure.

◆ raw() [2/2]

uv_loop_t * uvw::loop::raw ( )

noexcept

Gets the underlying raw data structure.

This function should not be used, unless you know exactly what you are doing and what are the risks.
Going raw is dangerous, mainly because the lifetime management of a loop, a handle or a request is in charge to the library itself and users should not work around it.

Warning: Use this function at your own risk, but do not expect any support in case of bugs.

Returns: The underlying raw data structure.

◆ resource()

template<typename R , typename... Args>

std::shared_ptr< R > uvw::loop::resource ( Args &&... args )

inline

Creates resources of any type.

This should be used as a default method to create resources.
The arguments are the ones required for the specific resource.

Use it as loop->resource<uvw::timer_handle>().

Returns: A pointer to the newly created resource.

Definition at line 154 of file loop.h.

◆ run()

int uvw::loop::run ( run_mode mode = run_mode::DEFAULT )

noexcept

Runs the event loop.

Available modes are:

loop::run_mode::DEFAULT: Runs the event loop until there are no more active and referenced handles or requests.
loop::run_mode::ONCE: Poll for i/o once. Note that this function blocks if there are no pending callbacks.
loop::run_mode::NOWAIT: Poll for i/o once but don’t block if there are no pending callbacks.

See the official documentation for further details.

Returns: Underlying return value.

◆ stop()

void uvw::loop::stop ( )

noexcept

Stops the event loop.

It causes run() to end as soon as possible.
This will happen not sooner than the next loop iteration.
If this function was called before blocking for I/O, the loop won’t block for I/O on this iteration.

◆ timeout()

std::pair< bool, time > uvw::loop::timeout ( ) const

noexcept

Gets the poll timeout.

Returns

A std::pair composed as it follows:

A boolean value that is true in case of valid timeout, false otherwise.
Milliseconds (std::chrono::duration<uint64_t, std::milli>).

◆ uninitialized_resource()

template<typename R , typename... Args>

std::shared_ptr< R > uvw::loop::uninitialized_resource ( Args &&... args )

inline

Creates uninitialized resources of any type.

Returns: A pointer to the newly created resource.

Definition at line 165 of file loop.h.

◆ update()

void uvw::loop::update ( ) const

noexcept

Updates the event loop’s concept of now.

The current time is cached at the start of the event loop tick in order to reduce the number of time-related system calls.
You won’t normally need to call this function unless you have callbacks that block the event loop for longer periods of time, where longer is somewhat subjective but probably on the order of a millisecond or more.

◆ walk()

template<typename Func >

void uvw::loop::walk ( Func callback )

inline

Walks the list of handles.

The callback is invoked once for each handle that is still active.

Parameters

callback A function to invoke once for each active handle.

Definition at line 280 of file loop.h.

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

src/uvw/loop.h

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ alive()

◆ close()

◆ configure()

◆ create() [1/2]

◆ create() [2/2]

◆ data() [1/2]

◆ data() [2/2]

◆ descriptor()

◆ fork()

◆ get_default()

◆ idle_time()

◆ metrics()

◆ now()

◆ raw() [1/2]

◆ raw() [2/2]

◆ resource()

◆ run()

◆ stop()

◆ timeout()

◆ uninitialized_resource()

◆ update()

◆ walk()