Changeset dc2b337 in rtems


Ignore:
Timestamp:
11/16/99 18:28:20 (24 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
71689d44
Parents:
1dbf307
Message:

Added task variable services.

Location:
doc/user
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/user/Makefile

    r1dbf307 rdc2b337  
    9696
    9797intr.texi: intr.t
    98         $(BMENU) -p "Task Manager TASK_WAKE_WHEN - Wake up when specified" \
     98        $(BMENU) -p "Task Manager TASK_VARIABLE_DELETE - Remove per task variable" \
    9999            -u "Top" \
    100100            -n "Clock Manager" ${*}.t
  • doc/user/task.t

    r1dbf307 rdc2b337  
    3232@item @code{@value{DIRPREFIX}task_wake_after} - Wake up after interval
    3333@item @code{@value{DIRPREFIX}task_wake_when} - Wake up when specified 
     34@item @code{@value{DIRPREFIX}task_variable_add} - Associate per task variable
     35@item @code{@value{DIRPREFIX}task_variable_delete} - Remove per task variable
    3436@end itemize
    3537
     
    286288task attempting to access the floating point unit is CPU dependent but will
    287289generally result in an exception condition.
     290
     291@subsection Per Task Variables
     292
     293@cindex per task variables
     294
     295Per task variables are used to support global variables whose value
     296may be unique to a task. After indicating that a variable should be
     297treated as private or pre-task.  The task can access and modify the
     298variable, but the modifications will not appear to other tasks, and
     299other tasks' modifications to that variable will not affect the value
     300seen by the task.  This is accomplished by saving and restoring the
     301variable's value each time a task switch occurs to or from the calling task.
     302
     303This feature can be used when a routine is to be spawned repeatedly as
     304several independent tasks.  Although each task will have its own stack,
     305and thus separate stack variables, they will all share the same static and
     306global variables.  To make a variable not shareable (i.e. a "global" variable
     307that is specific to a single task), the tasks can call
     308@code{rtems_task_variable_add} to make a separate copy of the variable
     309for each task, but all at the same physical address.
     310
     311Task variables increase the context switch time to and from the
     312tasks that own them so it is desirable to minimize the number of
     313task variables.  One efficient method is to have a single task
     314variable that is a pointer to a dynamically allocated structure
     315containing the task's private "global" data.
     316
     317A critical point with per-task variables is that each task must separately
     318request that the same global variable is per-task private.
    288319
    289320@subsection Building a Task Attribute Set
     
    15451576
    15461577A clock tick is required to support the functionality of this directive.
     1578
     1579@page
     1580
     1581@subsection TASK_VARIABLE_ADD - Associate per task variable
     1582
     1583@cindex per-task variable
     1584@cindex task private variable
     1585@cindex task private data
     1586
     1587@subheading CALLING SEQUENCE:
     1588
     1589@ifset is-C
     1590@findex rtems_task_variable_add
     1591@example
     1592rtems_status_code rtems_task_variable_add(
     1593  rtems_id  tid,
     1594  int      *ptr
     1595);
     1596@end example
     1597@end ifset
     1598
     1599@ifset is-Ada
     1600@example
     1601procedure Task_Variable_Add (
     1602   Id          : in     RTEMS.ID;
     1603   Ptr         : in     RTEMS.Address;
     1604   Result      :    out RTEMS.Status_Codes
     1605);
     1606@end example
     1607@end ifset
     1608
     1609@subheading DIRECTIVE STATUS CODES:
     1610@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
     1611@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
     1612@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
     1613@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks
     1614@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
     1615
     1616@subheading DESCRIPTION:
     1617This directive adds the memory location specified by the
     1618ptr argument to the context of the given task.  The variable will
     1619then be private to the task.  The task can access and modify the
     1620variable, but the modifications will not appear to other tasks, and
     1621other tasks' modifications to that variable will not affect the value
     1622seen by the task.  This is accomplished by saving and restoring the
     1623variable's value each time a task switch occurs to or from the calling task.
     1624
     1625@subheading NOTES:
     1626
     1627Task variables increase the context switch time to and from the
     1628tasks that own them so it is desirable to minimize the number of
     1629task variables.  One efficient method
     1630is to have a single task variable that is a pointer to a dynamically
     1631allocated structure containing the task's private `global' data.
     1632
     1633@page
     1634
     1635@subsection TASK_VARIABLE_DELETE - Remove per task variable
     1636
     1637@cindex per-task variable
     1638@cindex task private variable
     1639@cindex task private data
     1640
     1641@subheading CALLING SEQUENCE:
     1642
     1643@ifset is-C
     1644@findex rtems_task_variable_delete
     1645@example
     1646rtems_status_code rtems_task_variable_delete(
     1647  rtems_id  tid,
     1648  int      *ptr
     1649);
     1650@end example
     1651@end ifset
     1652
     1653@ifset is-Ada
     1654@example
     1655procedure Task_Variable_Delete (
     1656   Id          : in     RTEMS.ID;
     1657   Ptr         : in     RTEMS.Address;
     1658   Result      :    out RTEMS.Status_Codes
     1659);
     1660@end example
     1661@end ifset
     1662
     1663@subheading DIRECTIVE STATUS CODES:
     1664@code{@value{RPREFIX}SUCCESSFUL} - per task variable added successfully@*
     1665@code{@value{RPREFIX}INVALID_ID} - invalid task id@*
     1666@code{@value{RPREFIX}NO_MEMORY} - invalid task id@*
     1667@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported on remote tasks
     1668@code{@value{RPREFIX}NOT_DEFINED} - system date and time is not set
     1669
     1670@subheading DESCRIPTION:
     1671This directive removes the given location from a task's context.
     1672
     1673@subheading NOTES:
     1674
     1675NONE
     1676
Note: See TracChangeset for help on using the changeset viewer.