Stack of jumps

Overview

Definition of API to deal with thread-safe stack of jumps. More…

// typedefs

typedef struct tapi_jmp_point tapi_jmp_point;

// structs

struct tapi_jmp_point;

// global functions

tapi_jmp_point* tapi_jmp_push(const char* file, unsigned int lineno);
int tapi_jmp_pop(const char* file, unsigned int lineno);
int tapi_jmp_do(int val, const char* file, unsigned int lineno);
bool tapi_jmp_stack_is_empty(void);

// macros

#define TAPI_JMP_DO(_val)
#define TAPI_JMP_POP
#define TAPI_ON_JMP(x)
#define TAPI_ON_JMP_DO_SAFE_RC
#define TAPI_ON_JMP_DO_SAFE_VOID

Detailed Documentation

Definition of API to deal with thread-safe stack of jumps.

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Typedefs

typedef struct tapi_jmp_point tapi_jmp_point

Jump point (stack context to jump to)

Global Functions

tapi_jmp_point* tapi_jmp_push(const char* file, unsigned int lineno)

Allocate and push long jump point in a stack (saved stack context for non-local goto).

The routine is thread-safe using per thread stacks of jump points.

Parameters:

file	Name of the file where jump point is set
lineno	Number of line in the file

Returns:

Pointer to allocated long jump point.

See also:

tapi_jmp_do, tapi_jmp_pop

int tapi_jmp_pop(const char* file, unsigned int lineno)

Remove jump point set using tapi_jmp_push().

The routine is thread-safe using per thread stacks of jump points.

Parameters:

file	Name of the file where jump point is removed
lineno	Number of line in the file
TE_ENOENT	Stack of of jump points is empty

Returns:

Status code

See also:

tapi_jmp_push, tapi_jmp_do

int tapi_jmp_do(int val, const char* file, unsigned int lineno)

Do non-local goto a stack context saved using tapi_jmp_push().

The routine is thread-safe using per thread stacks of jump points.

Parameters:

val	Positive value to be returned by tapi_jmp_push (0 is mapped to TE_EOK)
file	Name of the file where jump is done
lineno	Number of line in the file
TE_ENOENT	Stack of of jump points is empty

Returns:

Status code

See also:

tapi_jmp_push

bool tapi_jmp_stack_is_empty(void)

Is stack of jumps empty?

c true Stack of jumps is empty c false Stack of jumps is not empty

Macros

#define TAPI_JMP_DO(_val)

Macro for convinient use of tapi_jmp_do().

#define TAPI_JMP_POP

Macro for convinient use of tapi_jmp_pop().

#define TAPI_ON_JMP(x)

Create jump point with actions to be done in the case of jump.

Parameters:

x	Actions to be done in the case of long jump (it is assumed that it does return, goto or exit)

#define TAPI_ON_JMP_DO_SAFE_RC

The same as TAPI_ON_JMP_DO_SAFE_VOID.

Should be used at the beginning of functions that return int.

#define TAPI_ON_JMP_DO_SAFE_VOID

Set jump point in case some function raise an exception. We should capture it here and then decide whether to push it back to user with jump, or just return.

Should be used at the beginning of functions that return void.