Lely core libraries 2.3.4
|
This header file is part of the event library; it contains the polling event loop declarations. More...
#include <lely/ev/future.h>
#include <lely/ev/poll.h>
#include <lely/libc/time.h>
#include <stddef.h>
Go to the source code of this file.
Typedefs | |
typedef struct ev_loop | ev_loop_t |
A polling event loop. | |
Functions | |
ev_loop_t * | ev_loop_create (ev_poll_t *poll, size_t npoll, int poll_task) |
Creates a new polling event loop. More... | |
void | ev_loop_destroy (ev_loop_t *loop) |
Destroys a polling event loop. More... | |
ev_poll_t * | ev_loop_get_poll (const ev_loop_t *loop) |
Returns a pointer to the polling instance used by the event loop, or NULL if the loop does not poll. | |
ev_exec_t * | ev_loop_get_exec (const ev_loop_t *loop) |
Returns a pointer to the executor corresponding to the event loop. | |
void | ev_loop_stop (ev_loop_t *loop) |
Stops the event loop. More... | |
int | ev_loop_stopped (const ev_loop_t *loop) |
Returns 1 if the event loop is stopped, and 0 if not. | |
void | ev_loop_restart (ev_loop_t *loop) |
Restarts an event loop. More... | |
size_t | ev_loop_wait (ev_loop_t *loop, ev_future_t *future) |
Equivalent to. More... | |
size_t | ev_loop_wait_until (ev_loop_t *loop, ev_future_t *future, const struct timespec *abs_time) |
Equivalent to. More... | |
size_t | ev_loop_wait_one (ev_loop_t *loop, ev_future_t *future) |
If the event loop has pending tasks, runs a single task. More... | |
size_t | ev_loop_wait_one_until (ev_loop_t *loop, ev_future_t *future, const struct timespec *abs_time) |
If the event loop has pending tasks, runs a single task. More... | |
size_t | ev_loop_run (ev_loop_t *loop) |
Equivalent to ev_loop_wait(loop, NULL) . | |
size_t | ev_loop_run_until (ev_loop_t *loop, const struct timespec *abs_time) |
Equivalent to ev_loop_wait_until(loop, NULL, abs_time) . | |
size_t | ev_loop_run_one (ev_loop_t *loop) |
Equivalent to ev_loop_wait_one(loop, NULL) . | |
size_t | ev_loop_run_one_until (ev_loop_t *loop, const struct timespec *abs_time) |
Equivalent to ev_loop_wait_one_until(loop, NULL, abs_time) . | |
size_t | ev_loop_poll (ev_loop_t *loop) |
Equivalent to ev_loop_run_until(loop, NULL) . | |
size_t | ev_loop_poll_one (ev_loop_t *loop) |
Equivalent to ev_loop_run_one_until(loop, NULL) . | |
void * | ev_loop_self (void) |
Returns the identifier of the calling thread. More... | |
int | ev_loop_kill (ev_loop_t *loop, void *thr) |
Interrupts an event loop running on the specified thread. More... | |
This header file is part of the event library; it contains the polling event loop declarations.
The polling event loop is an event loop suitable for use with asynchronous I/O operations. It is typically used in a thread pool to execute the tasks submitted to it through its associated executor. If no tasks are pending, the event loop can optionally poll for external events (through the abstract ev_poll_t polling interface), such as I/O completion or readiness notifications.
The event loop does not create its own threads. It depends on the user to execute one of the run functions (ev_loop_wait(), ev_loop_wait_until(), ev_loop_wait_one(), ev_loop_wait_one_until(), ev_loop_run(), ev_loop_run_until(), ev_loop_run_one(), ev_loop_run_one_until(), ev_loop_poll() and ev_loop_poll_one()). If not explicitly stopped, these functions will execute pending tasks as long as the event loop has outstanding work. In this context, outstanding work is defined as the sum of all pending and currently executing tasks, plus the number of calls to ev_exec_on_task_init(), minus the number of calls to ev_exec_on_task_fini(). If, at any time, the outstanding work falls to 0, the event loop is stopped as if by ev_loop_stop().
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Definition in file loop.h.
Creates a new polling event loop.
poll | a pointer to the polling instance to be used to poll for events. If poll is NULL, the event loop does not poll. |
npoll | the maximum number of threads allowed to poll (i.e., invoke ev_poll_wait(poll, ...) concurrently. If npoll is 0, there is no limit. If poll is NULL, this parameter is ignored. On platforms supporting I/O completion ports (Windows) it is generally most efficient to allow all threads to poll (i.e., npoll == 0 ), while on platforms using the reactor pattern (POSIX) it is best to allow a single polling thread (npoll == 1 ). |
poll_task | if poll_task is non-zero, a polling task is queued to the event loop and requeued when executed. This can prevent starvation, since the event loop otherwise only polls if no tasks are pending, which may never happen in CPU-bound situations. Under light loads, however, the extra polling overhead may harm performance. If poll is NULL, this parameter is ignored. |
void ev_loop_destroy | ( | ev_loop_t * | loop | ) |
void ev_loop_stop | ( | ev_loop_t * | loop | ) |
Stops the event loop.
Ongoing calls to ev_loop_run(), ev_loop_run_until(), ev_loop_run_one() and ev_loop_run_one_until() will terminate and future calls will return 0 immediately.
If this function is invoked explicitly, the loop MAY still contain outstanding work and it MAY NOT be safe to destroy submitted, but not completed, tasks. Invoke ev_loop_poll(), preceded by ev_loop_restart() if necessary, to ensure no outstanding work remains.
void ev_loop_restart | ( | ev_loop_t * | loop | ) |
Restarts an event loop.
size_t ev_loop_wait | ( | ev_loop_t * | loop, |
ev_future_t * | future | ||
) |
Equivalent to.
size_t ev_loop_wait_until | ( | ev_loop_t * | loop, |
ev_future_t * | future, | ||
const struct timespec * | abs_time | ||
) |
Equivalent to.
size_t ev_loop_wait_one | ( | ev_loop_t * | loop, |
ev_future_t * | future | ||
) |
If the event loop has pending tasks, runs a single task.
Otherwise, blocks while the loop has outstanding work or until the loop is stopped or the specified future (if not NULL) becomes ready. If the loop has no outstanding work, ev_loop_stop() is invoked. Note that more than one task MAY be executed if the task function invokes ev_exec_dispatch().
size_t ev_loop_wait_one_until | ( | ev_loop_t * | loop, |
ev_future_t * | future, | ||
const struct timespec * | abs_time | ||
) |
If the event loop has pending tasks, runs a single task.
Otherwise, blocks while the loop has outstanding work or until the loop is stopped or the specified future (if not NULL) becomes ready or the absolute timeout expires. If abs_time is NULL, this function will not block. If the loop has no outstanding work, ev_loop_stop() is invoked. Note that more than one task MAY be executed if the task function invokes ev_exec_dispatch().
Note that abs_time MUST be specified relative to the C11 TIME_UTC
time base. Depending on the platform, this base MAY be subject to clock changes while this function is executing.
void * ev_loop_self | ( | void | ) |
Returns the identifier of the calling thread.
This identifier can be used to interrupt a call to one of the run funtions from another thread with ev_loop_kill().
int ev_loop_kill | ( | ev_loop_t * | loop, |
void * | thr | ||
) |
Interrupts an event loop running on the specified thread.
In case of a nested event loop, this function only interrupts the inner loop.