RESTinio
Loading...
Searching...
No Matches
restinio::on_pool_runner_t< Http_Server > Class Template Reference

Helper class for running an existing HTTP-server on a thread pool without blocking the current thread. More...

#include <http_server_run.hpp>

Public Member Functions

 on_pool_runner_t (const on_pool_runner_t &)=delete
 on_pool_runner_t (on_pool_runner_t &&)=delete
 on_pool_runner_t (std::size_t pool_size, Http_Server &server)
 Initializing constructor.
template<typename On_Ok_Callback, typename On_Error_Callback>
void start (On_Ok_Callback &&on_ok, On_Error_Callback &&on_error)
 Start the server with callbacks that will be called on success or failure.
void start ()
 Start the server.
bool started () const noexcept
 Is server started.
template<typename Error_CB = abort_app_in_error_callback_t>
void stop (Error_CB error_cb=Error_CB{}) noexcept
 Stop the server.
void wait () noexcept
 Wait for full stop of the server.

Private Attributes

Http_Server & m_server
 HTTP-server to be run.
impl::ioctx_on_thread_pool_t< impl::external_io_context_for_thread_pool_tm_pool
 Thread pool for running the server.

Detailed Description

template<typename Http_Server>
class restinio::on_pool_runner_t< Http_Server >

Helper class for running an existing HTTP-server on a thread pool without blocking the current thread.

Usage of run() functions has some drawbacks. For example, the current thread on that run() is called, will be blocked until run() returns.

Sometimes it is not appropriate and leads to tricks like that:

// HTTP-server to be run on a thread pool.
// Separate worker thread for calling restinio::run().
std::thread run_thread{ [&server] {
16,
server) );
// Now this thread is blocked until HTTP-server will be finished.
} };
... // Some application specific code here.
// Now the server can be stopped.
run_thread.join();
Class for http-server.
constexpr break_signal_handling_t skip_break_signal_handling() noexcept
Make the indicator for absence of break signal handler.
run_on_thread_pool_settings_t< Traits > on_thread_pool(std::size_t pool_size)
A special marker for the case when http_server must be run on an thread pool.
void run(asio_ns::io_context &ioctx, run_on_this_thread_settings_t< Traits > &&settings)
Helper function for running http server until ctrl+c is hit.
void initiate_shutdown(http_server_t< Traits > &server)
Helper function for initiation of server shutdown.

Writing such code is a boring and error-prone task. The class on_pool_runner_t can be used instead:

// HTTP-server to be run on a thread pool.
// Launch HTTP-server on a thread pool.
16,
server
};
runner.start();
... // Some application specific code here.
// Now the server can be stopped.
runner.stop(); // (1)
runner.wait();
Helper class for running an existing HTTP-server on a thread pool without blocking the current thread...
void wait() noexcept
Wait for full stop of the server.
void start(On_Ok_Callback &&on_ok, On_Error_Callback &&on_error)
Start the server with callbacks that will be called on success or failure.
void stop(Error_CB error_cb=Error_CB{}) noexcept
Stop the server.

Moreover the code at point (1) in the example above it not necessary because on_pool_runner_t automatically stops the server in the destructor.

Since
v.0.5.1

Definition at line 783 of file http_server_run.hpp.

Constructor & Destructor Documentation

◆ on_pool_runner_t() [1/3]

template<typename Http_Server>
restinio::on_pool_runner_t< Http_Server >::on_pool_runner_t ( const on_pool_runner_t< Http_Server > & )
delete

◆ on_pool_runner_t() [2/3]

template<typename Http_Server>
restinio::on_pool_runner_t< Http_Server >::on_pool_runner_t ( on_pool_runner_t< Http_Server > && )
delete

◆ on_pool_runner_t() [3/3]

template<typename Http_Server>
restinio::on_pool_runner_t< Http_Server >::on_pool_runner_t ( std::size_t pool_size,
Http_Server & server )
inline

Initializing constructor.

Parameters
pool_sizeSize of thread pool.
serverServer instance to be run. NOTE. This reference must be valid for all life-time of on_pool_runner instance.

Definition at line 797 of file http_server_run.hpp.

Member Function Documentation

◆ start() [1/2]

template<typename Http_Server>
void restinio::on_pool_runner_t< Http_Server >::start ( )
inline

Start the server.

It just a shorthand for a version of start method with callbacks where all callbacks to nothing.

Definition at line 892 of file http_server_run.hpp.

◆ start() [2/2]

template<typename Http_Server>
template<typename On_Ok_Callback, typename On_Error_Callback>
void restinio::on_pool_runner_t< Http_Server >::start ( On_Ok_Callback && on_ok,
On_Error_Callback && on_error )
inline

Start the server with callbacks that will be called on success or failure.

The on_ok should be a function/functor with the format:

void () noexcept;

The on_error should be a function/functor with the format:

void (std::exception_ptr) noexcept;
Note
Both callbacks will be passed to http_server_t::open_async method. It means that on_error callback will be called for errors detected by open_async() methods.
Attention
Both callbacks should be noexcept functions/functors.

Usage example:

using my_http_server = restinio::http_server_t<some_traits>;
my_http_server server{...};
std::promise<void> run_promise;
auto run_future = run_promise.get_future();
runner.start(
// Ok callback.
[&run_promise]() noexcept {
run_promise.set_value();
},
// Error callback.
[&run_promise](std::exception_ptr ex) noexcept {
run_promise.set_exception(std::move(ex));
});
// Wait while HTTP-server started (or start failed).
run_future.get();
Since
v.0.6.7
Parameters
on_okA callback to be called if HTTP-server started successfully.
on_errorA callback to be called if HTTP-server is not started by some reasons. Please note that this callback is passed to http_server_t::open_async() and will be called only for errors detected by open_async() methods. If some error is detected outside of open_async() (for example a failure to start a thread pool) then on_error callback won't be called.

Definition at line 858 of file http_server_run.hpp.

◆ started()

template<typename Http_Server>
bool restinio::on_pool_runner_t< Http_Server >::started ( ) const
inlinenoexcept

Is server started.

Definition at line 901 of file http_server_run.hpp.

◆ stop()

template<typename Http_Server>
template<typename Error_CB = abort_app_in_error_callback_t>
void restinio::on_pool_runner_t< Http_Server >::stop ( Error_CB error_cb = Error_CB{})
inlinenoexcept

Stop the server.

This method stops the server by calling http_server_t::close_async() It means that stop will be performed asynchronously. To wait for the completion of stop operation the wait() method has to be used.

The simple usage:

using my_http_server = restinio::http_server_t<some_traits>;
my_http_server server{...};
runner.start(...);
...
// Some time later.
runner.stop();
... // Some other actions.
// Have to wait the completion of the stop() operation.
runner.wait();

This method accepts error_cb callback that will be called if an exception is thrown in http_server_t::close_async().

The error_cb is an optional parameter, an instance of abort_app_in_error_callback_t is used by default. It means that if an exception is thrown on http_server_t::close_async() then the whole application will be terminated. If such behavior is not desirable a user has to provide own error callback:

using my_http_server = restinio::http_server_t<some_traits>;
my_http_server server{...};
runner.start(...);
...
// Some time later.
runner.stop([](std::exception_ptr ex) {
... // Some handling of an exception.
});

But it's important to note that if an exception is thrown inside http_server_t::close_async() then the instance of http_server_t is in undefined state.

Note
This method is noexcept since v.0.6.7
Template Parameters
Error_CBType of the callback to be used if an exception is thrown inside http_server_t::close_async(). This callback should be noexcept functor (however, the noexceptness is not checked at the compile-time to have a possibility to use std::function as error callback). See abort_app_in_error_callback_t for a prototype of Error_CB functor.

Definition at line 965 of file http_server_run.hpp.

◆ wait()

template<typename Http_Server>
void restinio::on_pool_runner_t< Http_Server >::wait ( )
inlinenoexcept

Wait for full stop of the server.

Note
This method is noexcept since v.0.6.7

Definition at line 990 of file http_server_run.hpp.

Member Data Documentation

◆ m_pool

template<typename Http_Server>
impl::ioctx_on_thread_pool_t< impl::external_io_context_for_thread_pool_t > restinio::on_pool_runner_t< Http_Server >::m_pool
private

Thread pool for running the server.

Definition at line 790 of file http_server_run.hpp.

◆ m_server

template<typename Http_Server>
Http_Server& restinio::on_pool_runner_t< Http_Server >::m_server
private

HTTP-server to be run.

Definition at line 786 of file http_server_run.hpp.


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