Lely core libraries  2.3.4
stop.h File Reference

This header file is part of the utilities library; it contains the stop token declarations. More...

#include <lely/util/sllist.h>
Include dependency graph for stop.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  stop_func
 An object providing the means to register a callback function with an stop_token_t object. More...
 

Macros

#define STOP_FUNC_INIT(func)
 The static initializer for stop_func.
 

Typedefs

typedef struct stop_token stop_token_t
 An object providing the means to check if a stop request has been made for its associated stop_source_t object. More...
 
typedef struct stop_source stop_source_t
 An object providing the means to issue a stop request. More...
 

Functions

stop_token_tstop_token_acquire (stop_token_t *token)
 Acquires a reference to a stop token. More...
 
void stop_token_release (stop_token_t *token)
 Releases a reference to a stop token. More...
 
int stop_token_stop_requested (const stop_token_t *token)
 Checks if the stop-state associated with the specified stop token has received a stop request. More...
 
int stop_token_stop_possible (const stop_token_t *token)
 Checks if the stop-state associated with the specified stop token has received a stop request, or if it has an associated stop source that can still issue such an request. More...
 
int stop_token_insert (stop_token_t *token, struct stop_func *func)
 Registers a callback function with the specified stop token. More...
 
void stop_token_remove (stop_token_t *token, struct stop_func *func)
 Deregisters a callback function from the specified stop token. More...
 
stop_source_tstop_source_create (void)
 Creates a stop source with a new stop-state. More...
 
stop_source_tstop_source_acquire (stop_source_t *source)
 Acquires a reference to a stop source. More...
 
void stop_source_release (stop_source_t *source)
 Releases a reference to a stop source. More...
 
int stop_source_request_stop (stop_source_t *source)
 Issues a stop request to the stop-state associated with the specified stop source, if it has not already received a stop request. More...
 
int stop_source_stop_requested (const stop_source_t *source)
 Checks if the stop-state associated with the specified stop source has received a stop request. More...
 
stop_token_tstop_source_get_token (stop_source_t *source)
 Returns (a reference to) a stop token associated with the specified stop source's stop-state.
 

Detailed Description

This header file is part of the utilities library; it contains the stop token declarations.

The stop token API is based on the C++20 stop token interface.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

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 stop.h.

Typedef Documentation

◆ stop_token_t

typedef struct stop_token stop_token_t

An object providing the means to check if a stop request has been made for its associated stop_source_t object.

It is essentially a thread-safe "view" of the associated stop-state.

Definition at line 1 of file stop.h.

◆ stop_source_t

typedef struct stop_source stop_source_t

An object providing the means to issue a stop request.

A stop request is visible to all associated stop_token_t objects.

Definition at line 1 of file stop.h.

Function Documentation

◆ stop_token_acquire()

stop_token_t* stop_token_acquire ( stop_token_t token)

Acquires a reference to a stop token.

If token is NULL, this function has no effect.

Returns
token.
See also
stop_token_release()

Definition at line 104 of file stop.c.

◆ stop_token_release()

void stop_token_release ( stop_token_t token)

Releases a reference to a stop token.

If this is the last reference to the token, the token is destroyed. If no references remain to its associated stop source, the stop-state is destroyed. The object pointed to by token MUST NOT be referenced after this function has been invoked.

See also
stop_token_acquire()

Definition at line 121 of file stop.c.

◆ stop_token_stop_requested()

int stop_token_stop_requested ( const stop_token_t token)

Checks if the stop-state associated with the specified stop token has received a stop request.

Returns
1 if a stop request has been received, and 0 if not.
See also
stop_token_stop_requested()

Definition at line 143 of file stop.c.

◆ stop_token_stop_possible()

int stop_token_stop_possible ( const stop_token_t token)

Checks if the stop-state associated with the specified stop token has received a stop request, or if it has an associated stop source that can still issue such an request.

Returns
1 if a stop request has been received or still can be received, and 0 if not.
See also
stop_token_stop_requested()

Definition at line 149 of file stop.c.

◆ stop_token_insert()

int stop_token_insert ( stop_token_t token,
struct stop_func func 
)

Registers a callback function with the specified stop token.

If a stop request has already been issued for the associated stop source (i.e., stop_token_stop_requested() returns 1), the callback function is invoked in the calling thread before this function returns.

Returns
1 if the callback function was invoked, and 0 if not.
See also
stop_token_remove()

Definition at line 163 of file stop.c.

◆ stop_token_remove()

void stop_token_remove ( stop_token_t token,
struct stop_func func 
)

Deregisters a callback function from the specified stop token.

If the callback function is being invoked concurrently on another thread, this function does not return until the callback function invocation is complete. If the callback function is being invoked on the calling thread, this function does not wait until the invocation is complete. Hence it is safe to invoke this function from the callback function.

See also
stop_token_insert()

Definition at line 199 of file stop.c.

◆ stop_source_create()

stop_source_t* stop_source_create ( void  )

Creates a stop source with a new stop-state.

The stop source is destroyed once the last reference to it is released.

Returns
a reference to the new stop source on succes, or NULL on error. In the latter case, the error number can be obtained with get_errc().
See also
stop_source_release()

Definition at line 227 of file stop.c.

◆ stop_source_acquire()

stop_source_t* stop_source_acquire ( stop_source_t source)

Acquires a reference to a stop source.

If source is NULL, this function has no effect.

Returns
source.
See also
stop_source_release()

Definition at line 254 of file stop.c.

◆ stop_source_release()

void stop_source_release ( stop_source_t source)

Releases a reference to a stop source.

If this is the last reference to the source, the source is destroyed. If no references remain to its associated stop token, the stop-state is destroyed. The object pointed to by source MUST NOT be referenced after this function has been invoked.

See also
stop_source_acquire()

Definition at line 273 of file stop.c.

◆ stop_source_request_stop()

int stop_source_request_stop ( stop_source_t source)

Issues a stop request to the stop-state associated with the specified stop source, if it has not already received a stop request.

Once a stop is requested, it cannot be withdrawn. If a stop request is issued, any stop_func callbacks registered with the associated stop token are invoked synchronously on the calling thread.

Returns
1 if a stop request was issued, and 0 if not. In the latter case, another thread MAY still be in the middle of invoking a stop_func callback.
Postcondition
stop_source_stop_requested() returns 1.

Definition at line 291 of file stop.c.

◆ stop_source_stop_requested()

int stop_source_stop_requested ( const stop_source_t source)

Checks if the stop-state associated with the specified stop source has received a stop request.

Returns
1 if a stop request has been received, and 0 if not.
See also
stop_source_request_stop()

Definition at line 366 of file stop.c.