blc_command.h 5.82 KB
Newer Older
Arnaud Blanchard's avatar
Arnaud Blanchard committed
1
2
3
4
5
6
7
8
/* Basic Library for C/C++ (blclib)
 Copyright  ETIS — ENSEA, Université de Cergy-Pontoise, CNRS (2011 - 2015)
 
 Author: Arnaud Blanchard
 
 This software is governed by the CeCILL v2.1 license under French law and abiding by the rules of distribution of free software.
 You can use, modify and/ or redistribute the software under the terms of the CeCILL v2.1 license as circulated by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".
 As a counterpart to the access to the source code and  rights to copy, modify and redistribute granted by the license,
9
10
11
  users are provided only with a limited warranty and the software's author, the holder of the economic rights,  and the successive licensors have only limited liability.
  In this respect, the user's attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software,
  that may mean  that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
12
 Users are therefore encouraged to load and test the software's suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured
13
14
  and, more generally, to use and operate it in the same conditions as regards security.
  The fact that you are presently reading this means that you have had knowledge of the CeCILL v2.1 license and that you accept its terms. */
Arnaud Blanchard's avatar
Arnaud Blanchard committed
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

/*
 The usage formating follows the format of argparse in Python ( https://docs.python.org/3/library/argparse.html ).
Otherwise, we can be inspired from http://docopt.org
 */

/**
@defgroup blc_command command
Few functions helping for pseudo realtime applications.
@{*/

#ifndef BLC_COMMAND_H
#define BLC_COMMAND_H

#include "blc_tools.h"

Arnaud Blanchard's avatar
Arnaud Blanchard committed
31
/**
32
33
 period in microseconds
 0 for system as fast as possible, -1 for blocking on keyborad, -2 blocking after first iteration.
Arnaud Blanchard's avatar
Arnaud Blanchard committed
34
 Warning the period can be till 10ms longer than, asked. Problem of usleep/nano sleep */
Arnaud Blanchard's avatar
Arnaud Blanchard committed
35
36
#define BLC_COMMAND_LOOP(period) for(blc_command_loop_init(period); blc_command_loop_start();blc_command_loop_end())

37
typedef enum {BLC_QUIT=0, BLC_RUN, BLC_PAUSE, BLC_STEPS} type_blc_status;
Arnaud Blanchard's avatar
Arnaud Blanchard committed
38
typedef void (*type_blc_command_cb)(char const *argument, void *user_data);
39

40
41
42
43
44
45
/** Timer updated by blc_command_loop_start and  blc_command_loop_end (i.e. BLC_LOOP_FOR(<period>))
 It may be use by the application to get the absolute time in µs using blc_loop_timer.tv_sec*1000000+blc_loop_timer.tv_usec
 It should not be changed by the application
 */
extern struct timeval blc_loop_timer;

46
47
extern int blc_input_terminal, blc_output_terminal;
extern type_blc_status blc_status;
48
49
extern uint64_t blc_loop_iteration;
extern uint64_t blc_loop_iteration_limit;
Arnaud Blanchard's avatar
Arnaud Blanchard committed
50
extern long blc_command_loop_period;
51
52
extern FILE *blc_profile_file;

Arnaud Blanchard's avatar
Arnaud Blanchard committed
53
54
55

START_EXTERN_C

56
57
58
59




60
61
62
63
64
65
66
67
//void * to not need to include "semaphore.h"
void blc_loop_sem_to_unlock_on_stop(void *sem);

void blc_command_ask_quit();

void pause_cb();


Arnaud Blanchard's avatar
Arnaud Blanchard committed
68
69
70
///Add a command in the list of possible command lines from the user.
void blc_command_add(const char *command_name, type_blc_command_cb callback, const char *prompt, const char *help, void *user_data);

71
72
73
74
75
76
77
/**If the command is the format of a blc_channel, the command is sent to stdout and the command is not interpreted.
 /usr, /bin etc. may be interpreted as a blc_channel. use /usr/,  /bin/ in this case.
 Same for any command starting with . ^ / :
 */
void blc_command_forward_blc_channels();


78
79
80
///Remove a previously added command
void blc_command_remove(const char *command_name);

81
82
83
///Interpret the command passed in string.
void blc_command_interpret_string(char const *input_string, size_t size);

Arnaud Blanchard's avatar
Arnaud Blanchard committed
84
85
86
87
88
89
90
91
92
93
94
95
///Wait a input from the user (this id blocking) and interprets it depending on the blc_command list.
void blc_command_interpret();

///Like blc_command_interpret but does not block if there is nothing to read (return 0 in this case).
int blc_command_try_to_interpret();

//May not be useful
void *blc_command_interpret_loop(char const *option);

///Start a thread listinning to the user entry without blocking.
void blc_command_interpret_thread(char const *option, void (*ask_quitting_funtion)());

96
97
void blc_command_interpret_block();

Arnaud Blanchard's avatar
Arnaud Blanchard committed
98
99
100
101
102
103
104
///Display the list of blc_command with help.
void blc_command_display_help();

void blc_command_update_float_cb(char const *argument, void *float_pt);
void blc_command_update_double_cb(char const *argument, void *double_pt);
void blc_command_update_int_cb(char const *argument, void *int_pt);

105
106
107
108
109
110
111
112
int blc_loop_try_add_waiting_semaphore(void *semaphore);
int blc_loop_try_add_posting_semaphore(void *semaphore);

/**The loop will start only once the semaphore is available.
 The waiting time does not count is the loop timing.
 When quitind these semaphores will be posted to be unlock the waiting loop
 We use void* instead of sem_t* to not force every body to include semaphore.h*/
void blc_loop_add_waiting_semaphore(void *semaphore);
Arnaud Blanchard's avatar
Arnaud Blanchard committed
113

114
115
116
/**In the end the loop, this sempahore will be posted
 We use void* instead of sem_t* to not force every body to include semaphore.h*/
void blc_loop_add_posting_semaphore(void *semaphore);
Arnaud Blanchard's avatar
Arnaud Blanchard committed
117

118
119
120
/**The loop willt start only once the waiting_callback callback will be executed. 
 The waiting time does not count is the loop timing*/
void blc_loop_add_waiting_callback( void(*waiting_callback)(void*), void *user_data);
121
122
123
124
/** Loop period in ms.
- 0 the system is as fast as possible
- -1 it blocks on keyboard
- -2 it blocks on keyboard after a first iteration*/
Arnaud Blanchard's avatar
Arnaud Blanchard committed
125
126
127
128
129
130
131
132
133
134
135
136
137
138
void blc_command_loop_init(long loop_period);
int blc_command_loop_start();
void blc_command_loop_end();

/** Stop a textual program
 * - Send a quitting message with the name of the app on stderr.
 * - Send 'q' and flush on stdout if it is a piped output
 * - quit with no error (0).
 */
void blc_quit();

END_EXTERN_C
#endif
///@}