el_process.h File Reference

#include "el_common.h"
#include "el_clock.h"

Go to the source code of this file.

Macros
#define	EL_PROCESS_MAX_NUM   7
#define	EL_PROCESS   void

Typedefs
typedef void(*	el_process )(void *)

Functions
el_index	el_launch_process (el_process func, void *arg)
	execute a function in a process More...
void	el_process_wait (el_time t_ms)
	wait for a period of time More...
void	el_process_wait_fraction (unsigned int num, unsigned int den)
	wait for a period of time specified as a fraction More...
void	el_process_cooperate ()
	Introduce an atomic wait so other processes can be executed. More...
void	el_process_resume (el_index process_idx)
	finish the waiting period of a process immediately More...
void	el_kill_process (el_index process_idx)
	kill the process (the abnormal way to end a process) More...
el_index	el_get_local_process_index ()
	get index of the process where this function is called More...

Detailed Description

Author

Jianing Chen

Function Documentation

el_index el_launch_process	(	el_process	func,
		void *	arg
	)

execute a function in a process

Parameters

func	the pointer to the function to be executed (entry function)
arg	an arguments passed to the function to be executed

Returns

the index of the process (-1 if failed)

This function can execute a function (entry function) in a process with the given argument (as "func(arg);"). Maxmum number of processes is 7.

The entry function must be a function that takes a void pointer or a el_handle as the argument and returns void. For example:

void my_process(void*arg){
    ...
}

void el_process_wait

(

el_time

t_ms

)

wait for a period of time

Parameters

t_ms	time in millisecond

This function induces a time delay. It can only be used in a process.

void el_process_wait_fraction	(	unsigned int	num,
		unsigned int	den
	)

wait for a period of time specified as a fraction

Parameters

num	numerator of the time in seconds.
den	denominator of the time in seconds.

This function induces a time delay of (num/den) seconds in a process.

void el_process_cooperate

(

)

Introduce an atomic wait so other processes can be executed.

This function introduce an atomic delay, which give other processes a chance to execute. Once this process get a chance to execute again, it will continue execute. Therefore, unlike "el_process_wait", "el_process_cooperate" does not cause a notable time delay. It can be used in polling mechanism inside a process. For example, the following scheme can be used to waiting for a condition to become true:

...
// wait for a condition
do{
    el_process_cooperate();
}while(some_condition_is_not_true());
...

There could be a section in a process that simply cost large amount of computation and thus make the process alone occupy the CPU for a long time. "el_process_cooperate" should be called in appropriate positions in a process of such types. For instance, in a triple-nested loop with a loop body that is also time-costly, add a "el_process_cooperate();" after the middle loop:

...
// some big computation program
for(k=0;k<15;k++){
    for(j=0;j<40;j++){
        for(i=0;i<10;i++){
            some_complicated_algorithm(i,j,k);
        }
    }
    el_process_cooperate();
}
...

void el_process_resume

(

el_index

process_idx

)

finish the waiting period of a process immediately

Parameters

process_idx

the index of the process

This function can make a process in el_process_wait finish the waiting period immediately.

void el_kill_process

(

el_index

process_idx

)

kill the process (the abnormal way to end a process)

Parameters

process_idx

the index of the process to be killed

This function can be used to forcefully stop a process while it is waiting (e.g. when it entered el_process_wait or el_process_cooperate). Unlike the relation between 'create' and 'delete', a launched process are not supposed to be killed. A process ends normally when its entry function returns (reach the end of the function).

Note: Killing a process causes all the local variables within to be lost. If a dynamically created object is referable only through such a local variable, a memory leak is resulted (unable to 'free'/'delete' through the pointer/handle anymore).

el_index el_get_local_process_index

(

)

get index of the process where this function is called

Returns

index of the process

When this function is not called within a process, it returns -1.