task相关函数的功能和用法.doc

task相关函数的功能和用法
版本号
整理人
整理日期
备注
V1.0
胡军、王雪、张达蔚、
吴旻、张丽丽、白艳滨
2008-7-10
初稿（培训讨论后整理）

1. task_create (by HJ)

·原型：task_t* task_create(void (*Function)(void*),
  void* Param,
    size_t StackSize,
    int Priority,
    const char* Name,
    task_flags_t flags )；

·参数： void (*Function)(void*)
指向任务函数的入口即函数名。
void* Param
提供给Function的入口参数，如果参数较多，可以组合成结够体，再提供此结构体的地址作为参数即可。
size_t StackSize
任务所用的栈的大小。
int Priority
创建任务的优先级。
const char* Name
任务的名称，主要是用来标示任务队列里的不同任务。
task_flags_t flags
关于任务的一些附加信息，一般定义为0，及标示为默认的行为具体如下表：

Task flags
Task behavior
Target
0
创建一个OS20的默认的task.
任何
task_flags_high_priority_process
创建一个高优先级的人进程 (在ST20C1中被忽视).
ST20C2
task_flags_suspended
Create the task already suspended.
任何

·返回值：如果创建成功返回指向该结构体的指针，否则返回NULL。

·功能描述：此函数为创建一个具有给定优先级的任务。

·应用举例：
#include < stdio.h >
#include < stdlib.h >
#include < ostime.h >
#include < task.h >
#include < semaphor.h >
#define ONE_SECOND 100
#define USER_PRIORITY 1
#define USER_WS_SIZE 2048

struct sig_params
{
semaphore_t *Ready;
int Count;
};

void signal_task(void* p)

{
struct sig_params* Params = (struct sig_params*)p;
int j;
for (j = 0; j < Params->Count; j++)
{
semaphore_signal (Params->Ready);
task_delay(ONE_SECOND);
}
}

int main()
{
task_t* Task;
struct sig_params params;
Task = task_create (signal_task, &params,
USER_WS_SIZE, USER_PRIORITY, "Signal", 0);
if (Task == NULL)
{
printf ("Error : create. Unable to create task\n");
exit (EXIT_FAILURE);
}
}

2. task_data (by HJ)

·原型：void* task_data( task_t* Task )；

·参数：task_t* Task
指向任务接构task_t的指针。

·返回值：返回任务的数据指针，如果任务为空则返回当前正在运行任务的数据指针。

·功能描述：此函数调用返回该任务的数据指针。

·应用举例：
#include < stdio.h >
#include < stdlib.h >
#include < task.h >
#define running 1
#define USER_WS_SIZE 2048
#define USER_PRIORITY 2
task_t *Task1;
void task1 ( void )
{
while( running )
{
task_data( task_t* task1)
task_delay( 1000 );
}
}

int main()
{
Task1 = task_create (( void ( * )( void* )) task1,
NULL,
USER_WS_SIZE,
USER_PRIORITY,
"low",
0);
printf( "task1 is created!\n" );
if ( NULL == Task1 )
{
printf ( "Error : create. Unable to create task\n" );
exit ( EXIT_FAILURE );
}
while( running )
{
task_delay( 1000 );
}
}

3. task_data_set (by HJ)

·原型：void* task_data_set( task_t* Task, void* NewData )；

·参数：task_t* Task
指向任务结构task_t的指针。
void* NewData
新的指向数据的指针。

·返回值：返回该任务先前的（设置新的数据指针之前）数据指针，如果所设置的任务为空则返回正在运行的任务（此时数据指针已被跟新）之前的数据指针。

·功能描述：此函数设置任务的新的数据指针如果被设置的任务为空则设置当前正在运行的任务的数据指针。

·应用举例：
#include < stdio.h >
#include < stdlib.h >
#include < task.h >
#define running 1
#define USER_WS_SIZE 2048
#define USER_PRIORITY 2
task_t *Task1;
void task1 ( void )
{
while( running )
{
task_data_set(Task1, (void *)0x00000001 );
task_delay( 1000 );
}
}

int main()
{
Task1 = task_create (
( void ( * )( void* )) task1,
NULL,
USER_WS_SIZE,
USER_PRIORITY,
"low",
0);
printf( "task1 is created!\n" );

if ( NULL == Task1 )
{
printf ( "Error : create. Unable to create task\n" );
exit ( EXIT_FAILURE );
}
while( running )
{
task_delay( 1000 );
}
}

4. task_context (by HJ)

·原型：task_context_t task_context( task_t **task,int* level )

·参数：task_t **task
返回的任务描述。
int* level
返回的中断水平。

·返回值：一个os20的任务，一个高优先级的进程还是一个中断。

·功能描述： 该函数返回一个被调用上下文的描述，是否为一个任务，一个中断或者一个高优先级的进程，主要有下面三个值来表明：
当为 OS20 task时, 返回 task_context_task；
当为 interrupt handler时,返回 task_context_interrupt；
当为high priority process 对于 ST20C2内核时, 返回task_context_hpp。
需要说明的是，如果返回的task不为空则说明被调用的是一个os20的任务或者一个高优先级的进程，则相应的task_t信息被写入task所指向的内容，同样的如果level不为空则说明为一个中断，并且中断水平被写入level所指向的单元。

·应用举例：
#include < stdio.h >
#include < stdlib.h >
#include < task.h >
#define running 1
#define USER_WS_SIZE 2048
#define USER_PRIORITY 2
task_t *Task1;
int *level;
task_context_t contxt;

void task1 ( void )
{
while( running )
{
contxt=task_context(&Task1,level);
task_delay( 1000 );
}
}

int main()
{
Task1 = task_create (( void ( * )( void* )) task1,
NULL,
USER_WS_SIZE,
USER_PRIORITY,
"low",
0);
printf( "task1 is created!\n" );
if ( NULL == Task1 )
{
printf ( "Error : create. Unable to create task\n" );
exit ( EXIT_FAILURE );
}

while( running )
{
task_delay( 1000 );
}
}

5. task_create_sl (by HJ)

·原型：task_t* task_create_sl( void (*Function)(void*),
    void* Param,
    void* StaticLink,
    size_t StackSize,
    int Priority,
    const char* Name,
    task_flags_t flags );
·参数：void* StaticLink
当调用Function是需要用到此静态链接，即程序静态的地址。
其他参数同task_create。

·返回值：如果创建成功返回指向该结构体的指针，否则返回NULL。

·功能描述：与task_create()功能相同，不同的是此函数多了个静态链接地址。

6. task_delay (by WX)

·原型：void task_delay(clock_t delay);

·参数：clock_t delay
任务延迟的时间段。

·返回值：无。

·功能描述：调用此函数，使任务等待一段指定的时间，这段时间以tick（滴答）为单位，即任务延迟这段时间后才继续执行。如果给出的时间为负值，则不延迟。

7. task_delay_until (by WX)

·原型：void task_delay_until(clock_t delay);

·参数：clock_t delay
任务延迟到delay指定的时刻再执行。

·返回值：无。

·功能描述：调用此函数，使任务等待，直到参数指定的时刻再继续执行。与task_delay不同，task_delay_until中参数给出的是绝对的时间点。如果参数中的时刻在当前时刻之前，则不延迟。
6, 7这两个函数应用于在一个特定的时刻引起某个事件。一个高优先级的任务可以等待一段时间，这段时间过后，如果运行着的任务的优先级比他低，他便会抢占使用CPU。

·应用举例：
#include < stdio.h >
#include < stdlib.h >
#include < task.h >

#include <ostime.h>
clock_t time;
time = time_now();
while (1)
{
time = time_plus (time, delay);
task_delay_until(time);
initiate_regular_event();
}

8. task_delete (by WX)

·原型：int task_delete(task_t* task);

·参数：task_t* task
指向要删除的task结构体的指针。

·返回值：int类型，-1表示调用失败；0表示调用成功。

·功能描述：在任务列表中移除此任务，并且使系统回收其占用的资源。一个任务只有在结束后才可以被delete，否则task_delete调用会失败。
用task_creat创建的task在使用task_delete后系统自动调用memory_deallocate函数释放所占内存，如果用task_init创建的task，用完task_delete后还需手动释放其所占内存。

9. task_exit (by WX)

·原型：void task_exit(int param);

·参数：int param
自定义的整型数，传递给onexit handler。

·返回值：无。

·功能描述：终止当前任务。
任务终止既可以通过函数的返回，也可以通过task_exit调用来实现。这两种情况下都可以指定退出状态，前一种情况，退出状态即函数的返回值，如果调用task_exit，则退出状态通过参数来指定。然后这个值被用于onexit_handler函数。

·应用举例：
#include <stdio.h>
#include <stdlib.h>
#include <task.h>
void Task1( void )
{
while (1)
{
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
debugmessage("task1\n");
task_delay(2000);
task_exit(-1);
}
}
void Task2(void)
{
while (1)
{
debugmessage("task2\n");
debugmessage("task2\n");
debugmessage("task2\n");
debugmessage("task2\n");
debugmessage("task2\n");
task_delay(2000);
}
}
int main (void)
{
task_t *task1, *task2;
task1 = task_create((void (*)(void* )) Task1, 0, 1024, 7, "Task1", 0);
task2 = task_create( (void (*)(void*)) Task2, 0, 1024, 7, "Task2", 0);
while(1)
{
task_delay(20000);
}
}
运行结果：（先打印10遍task1，以后全是task2）
task1
task1
task1
task1
task1
task1
task1
task1
task1
task1
task2
task2
task2
task2
task2
task2
task2
task2
…

10. task_id (by WX)

·原型：task_t* task_id (void);

·参数：无。

·返回值：返回一个指向当前任务结构体的指针。

·功能描述：获取当前任务的相关信息。
对于OS20系统中高优先级的任务调用task_id函数，会花费很长的执行时间，而且他也不能被中断服务程序调用。为了避免这些问题，可以使用task_context函数。

·应用举例：
#include <stdio.h>
#include <stdlib.h>
#include <task.h>

void task_exit(int param)
{
task_t *Task;

FATAL_ERROR_IF_INTERRUPT();
FATAL_ERROR_IF_LOCKED();

Task = task_id();
task_exit_generic(Task, param, task_exit_flags_safe_exit);
}

11. task_kill (by ZDW)
·原型：int task_kill( task_t* task , int status ,task_kill_flags_t flags );

·参数：task_t* task
要被强制终止的task
int status
这个task的出口位置
task_kill_flags_t flags
标记

·返回值： 如果task被成功kill掉返回0,否则返回-1 。

·功能描述： 强制终止一个task ，kill只会终止task，并不会delete掉task，可以在kill后delete，如下：
void tidy_up(task_t* task, int status)
{
  task_kill(task, status, 0);
  task_wait(&task, 1, TIMEOUT_INFINITY);
  task_delete(task);
}

·应用举例：
#include<debug.h>
#include "task.h"
#include<stdio.h>
int i = 0;
void Task1(void)
{
while(i < 50)
{
i++;
debugmessage("task1\n");
task_delay(2000);
}
}

int main(void)
{
task_t *task;
int a = 0;
int kill = 0;
task = task_create((void (*)(void*)) Task1, 0, 1024, 7, "Task1", 0);
while(a<3)
{
task_delay(2000);
a++;
kill = task_kill( task, 0, 0 );
printf( "kill=%d\n", kill );
}
}
运行结果：
task1
kill=0
kill=-1
kill=-1

12. task_immortal (by ZDW)
·原型： void task_immortal( void );

·参数： 无

·返回值： 无

·功能描述： task_immortal函数可以保护当前task不被kill，如果在task_immortal的同时task_kill，当前task不会马上死掉，直到出现task_mortal后。

·应用举例：
#include<debug.h>
#include "task.h"
#include<stdio.h>
int i = 0;
void Task1(void)
{
task_ immortal()
while(i < 50)
{
i++;
debugmessage("task1\n");
task_delay(2000);
}
}

int main(void)
{
task_t *task;
int a = 0;
int kill = 0;
task = task_create((void (*)(void*)) Task1, 0, 1024, 7, "Task1", 0);
while(a<3)
{
task_delay(2000);
a++;
kill = task_kill( task, 0, 0 );
printf( "kill=%d\n", kill );
}
}
运行结果：
task1
kill=0
task1
kill=0
task1
kill=0
（疑问：为什么kill仍然返回0？）

13. task_lock (by ZDW)
·原型： void task_lock( void );
·参数： 无
·返回值： 无
·功能描述： 让task独占CPU资源。task_lock函数防止当前task没完成前cpu被其他task抢占。task_lock被调用时一定要和task_unlock成对使用，否则会产生死锁。 task_lock可以被嵌套使用， 但是同时必须相等数量的task_unlock，否则task_lock不会被释放。
·应用举例：
#include "task.h"
#include "debug.h"
int i = 0;
void Task1(void)
{
task_lock();
while(i < 50)
{
i++;
debugmessage("task1\n");
}
task_unlock();
}

void Task2(void)
{
while(1)
{
debugmessage("task2\n");
}
}

void main(void)
{
task_t *task;
task = task_create((void (*)(void*)) Task1, 0, 1024, 7, "Task1", 0);
task = task_create((void (*)(void*)) Task2, 0, 1024, 7, "Task2", 0);
while(1)
{
task_delay(2000);
}
}
运行结果：连续输出50次task1后在开始输出task2。

14. task_init (by ZDW)
·原型： int task_init( void (*Function)(void*),
  void* Param,
  void* Stack,
  size_t StackSize,
  task_t* Task,
  tdesc_t* Tdesc,
  int Priority,
  const char* Name,
  task_flags_t flags );

·参数： void (*Function)(void*)
指向task函数地址的指针变量
void* Param
传递给函数的参数
void* Stack
指向栈的指针变量
size_t StackSize
栈的所占字节数
task_t* Task
指向这个task的任务控制块的指针变量
tdesc_t* Tdesc
指向这个task的描述的指针变量
int Priority
task调度优先级
const char* Name
task的名字，会被调试器用到
task_flags_t flags
实现task行为的不同的标记

·返回值： 成功返回0，错误否则返回-1 （当优先级不合法或者栈的size太小时）。

·功能描述：初始化task。task_init() 建立一个task并且启动这个task。

·应用举例：
#include <task.h.>
#define STACK_SIZE 1024
task_t task;
tdesc_t tdesc;
char stack[STACK_SIZE];
task_init(fn_ptr, NULL, stack, STACK_SIZE,
&task, &tdesc, 10, "test", 0);

15. task_init_sl (by ZDW)
·原型： int task_init_sl( void (*Function)(void*),
  void* Param,
  void* StaticLink,
  void* Stack,
  size_t StackSize,
  task_t* Task,
  tdesc_t* Tdesc,
  int Priority,
  const char* Name,
  task_flags_t flags );

·参数： void (*Function)(void*)
指向task函数地址的指针变量
void* Param
传递给函数的参数
void* StaticLink
调用函数是被用到的静态链接
void* Stack
指向栈的指针变量
size_t StackSize
栈的所占字节数
task_t* Task
指向这个task的任务控制块的指针变量
tdesc_t* Tdesc
Pointer to the task's descriptor
int Priority
task调度优先级
const char* Name
task的名字，会被调试器用到
task_flags_t flags
实现task行为的不同的标记

·返回值： 成功返回0，错误返回-1（当优先级不合法或者栈的size太小时）。

·功能描述：初始化指定静态链接的task。

16. task_name (by WM)

·原型：const char*task_name( task_t *task );

·参数：task_t* Task
要返回名字的task。

·返回值：被指定的task的名字。

·功能描述：这个函数返回被指定task的名字，如果task为null,则返回当前task的，task的名字是在创建它时设定的。

·应用举例：
#include < stdio.h >
#include < stdlib.h >
#include < string.h >
#include < task.h >
#include < semaphor.h >

#define ONE_SECOND 100
#define running 1
#define USER_WS_SIZE2 2048
#define USER_PRIORITY2 0
#define USER_WS_SIZE3 2048
#define USER_PRIORITY3 0

void task_priority2( void )
{
while( running )
{
printf(" task1 1\n task1 2\n task1 3\n task1 4\n task1 5\n task1 6\n task1 7\n task1 8\n task1 9\n task1 10\n");
}

}
void task_priority3( void )
{
while( running )
{
printf(" task2 1\n task2 2\n task2 3\n task2 4\n task2 5\n");
}
}

int main() {

task_t *Task1;
task_t *Task2;
char ch_name[100];

Task1 = task_create (
( void ( * )( void* ))task_priority2,
NULL,
USER_WS_SIZE2,
USER_PRIORITY2,
"low",
0);
printf( "task1 is created!\n" );

Task2 = task_create (
( void ( * )( void* ))task_priority3,
NULL,
USER_WS_SIZE3,
USER_PRIORITY3,
"middle",
0);
printf( "task2 is created!\n" );

if ( NULL == Task1 )
{
printf ( "Error : create. Unable to create task\n" );
exit ( EXIT_FAILURE );
}
if ( NULL == Task2 )
{
printf ( "Error : create. Unable to create task\n" );
exit ( EXIT_FAILURE );
}

strcpy(ch_name,task_name(Task1));
printf ("%s\n",ch_name);

while( running )
{
task_delay( 1000 );
}
}

17. task_priority (by WM)

·原型：int task_priority( task_t* Task );

·参数：task_t* Task
指向task结构体的指针

·返回值：返回task的优先级，如果task为null，则返回当前task的优先级。

·应用举例：
#include < stdio.h >
#include < stdlib.h >
#include < string.h >
#include < task.h >
#include < semaphor.h >

#define ONE_SECOND 100
#define running 1
#define USER_WS_SIZE2 2048
#define USER_PRIORITY2 0
#define USER_WS_SIZE3 2048
#define USER_PRIORITY3 0

void task_priority2( void )
{
while( running )
{
printf(" task1 1\n task1 2\n task1 3\n task1 4\n task1 5\n task1 6\n task1 7\n task1 8\n task1 9\n task1 10\n");

}

}
void task_priority3( void )
{
while( running )
{
printf(" task2 1\n task2 2\n task2 3\n task2 4\n task2 5\n");
}
}

int main() {

task_t *Task1;
task_t *Task2;
int i_pri;

Task1 = task_create (
( void ( * )( void* ))task_priority2,
NULL,
USER_WS_SIZE2,
USER_PRIORITY2,
"low",
0);
printf( "task1 is created!\n" );

Task2 = task_create (
( void ( * )( void* ))task_priority3,
NULL,
USER_WS_SIZE3,
USER_PRIORITY3,
"middle",
0);
printf( "task2 is created!\n" );

if ( NULL == Task1 )
{
printf ( "Er