- Main Page
- Modules
- Data Structures
- Files

# Flag Functions
[User API: Pico Layer]

## Functions
POSEXTERN POSFLAG_t | posFlagCreate (void)
POSEXTERN void | posFlagDestroy (POSFLAG_t flg)
POSEXTERN VAR_t | posFlagSet (POSFLAG_t flg, UVAR_t flgnum)
POSEXTERN VAR_t | posFlagGet (POSFLAG_t flg, UVAR_t mode)
POSEXTERN VAR_t | posFlagWait (POSFLAG_t flg, UINT_t timeoutticks)

## Detailed Description

Flags are one-bit semaphores. They can be used to simulate events. A thread can simultaneousely wait for multiple flags to be set, so it is possible to post multiple events to this thread. The count of events a flag object can handle is only limited by the underlaying architecutre, the maximum count is defined as MVAR_BITS - 1.

## Function Documentation

POSEXTERN POSFLAG_t posFlagCreate | ( | void |  | ) |

| Flag function. Allocates a flag object. A flag object behaves like an array of one bit semaphores. The object can hold up to MVAR_BITS - 1 flags. The flags can be used to simulate events, so a single thread can wait for several events simultaneously. Returns: handle to the new flag object. NULL is returned on error. Note: POSCFG_FEATURE_FLAGS must be defined to 1 to have flag support compiled in. See also: posFlagGet, posFlagSet, posFlagDestroy

POSEXTERN void posFlagDestroy | ( | POSFLAG_t | flg | ) |

  | Flag function. Frees an unused flag object again. Parameters:
  | flg | handle to the flag object.
Note: POSCFG_FEATURE_FLAGS must be defined to 1 to have flag support compiled in. POSCFG_FEATURE_FLAGDESTROY must be defined to 1 to have this function compiled in. See also: posFlagCreate

POSEXTERN VAR_t posFlagGet | ( | POSFLAG_t | flg,
|  | UVAR_t | mode
| ) |

  | Flag function. Pends on a flag object and waits until one of the flags in the flag object is set. Parameters:
  | flg | handle to the flag object.
  | mode | can be POSFLAG_MODE_GETSINGLE or POSFLAG_MODE_GETMASK.
Returns: the number of the next flag that is set when mode is set to POSFLAG_MODE_GETSINGLE. When mode is set to POSFLAG_MODE_GETMASK, a bit mask with all set flags is returned. A negative value is returned on error. Note: POSCFG_FEATURE_FLAGS must be defined to 1 to have flag support compiled in. See also: posFlagCreate, posFlagSet, posFlagWait

POSEXTERN VAR_t posFlagSet | ( | POSFLAG_t | flg,
|  | UVAR_t | flgnum
| ) |

  | Flag function. Sets a flag bit in the flag object and sets the task that pends on the flag object to running state. Parameters:
  | flg | handle to the flag object.
  | flgnum | Number of the flag to set. The flag number must be in the range of 0 .. MVAR_BITS - 2.
Returns: zero on success. Note: POSCFG_FEATURE_FLAGS must be defined to 1 to have flag support compiled in. See also: posFlagCreate, posFlagGet, posFlagWait

POSEXTERN VAR_t posFlagWait | ( | POSFLAG_t | flg,
|  | UINT_t | timeoutticks
| ) |

  | Flag function. Pends on a flag object and waits until one of the flags in the flag object is set or a timeout has happened. Parameters:
  | flg | handle to the flag object.
  | timeoutticks | timeout in timer ticks (see HZ define and MS macro). If this parameter is set to zero, the function immediately returns. If this parameter is set to INFINITE, the function will never time out.
Returns: a mask of all set flags (positive value). If zero is returned, the timeout was reached. A negative value denotes an error. Note: POSCFG_FEATURE_FLAGS must be defined to 1 to have flag support compiled in. POSCFG_FEATURE_FLAGWAIT must be defined to 1 to have this function compiled in. See also: posFlagCreate, posFlagSet, posFlagGet, HZ, MS