Locking

This GOAL core module provides functions to lock resources in the GOAL system. This module supports two types of lock mechanism:

counting semaphore, specified by the enum GOAL_LOCK_COUNT
binary mutex, specified by the enum GOAL_LOCK_BINARY

The behavior for waiting on a semaphore or mutex can be configured. Active or passive waiting is possible.
The implementation of the lock mechanisms is platform-specific. In GOAL systems with an operating system the lock mechanisms use the appropriate services of the operating system.
The system is halted by function goal_targetHalt() in case of an error.

GOAL files:
- goal_lock.[h,c]
example:
- …\goal\appl\00410_goal\task_lock

Platform API

GOAL requires the following indication function to connect the GOAL system to the appropriate services of the operating system:

Table: goal_targetLockInit()

Prototype	GOAL_STATUS_T goal_targetLockInit(void)
Description	This indication function initializes the locking mechanism on the operating system. This function is called in the stage GOAL_STAGE_LOCK_PRE in state GOAL_FSA_INIT_GOAL.
Parameters	None
Return values	GOAL return status, see Chapter: GOAL status
Category	Mandatory
Condition	None

Table: goal_targetLockShutdown()

Prototype	GOAL_STATUS_T goal_targetLockShutdown(void)
Description	This indication function shutdowns the locking mechanism on the operating system. This function is called in the stage GOAL_STAGE_LOCK_PRE in state GOAL_FSA_SHUTDOWN.
Parameters	None
Return values	GOAL return status, see Chapter: GOAL status
Category	Mandatory
Condition	None

Table: goal_targetLockCreate()

Prototype	GOAL_STATUS_T goal_targetLockCreate(GOAL_LOCK_TYPE_T lockType, GOAL_LOCK_T *pLock, uint32_t valInit, uint32_t valMax)
Description	This indication function creates a lock on the operating system.
Parameters	lockType	type of the lock: GOAL_LOCK_BINARY: GOAL_LOCK_COUNT:
	pLock	handle for the created lock
	valInit	counting semaphores: initial value of the lock Number of instances which shall be marked as already in use, normally. binary mutex: 0
	valMax	counting semaphores: maximal value of the lock Number of maximal instances which shall be use this lock, normally. binary mutex: 1
Return values	GOAL return status, see Chapter: GOAL status
Category	Mandatory
Condition	None

Table: goal_targetLockDelete()

Prototype	GOAL_STATUS_T goal_targetLockDelete(GOAL_LOCK_T *pLock)
Description	This indication function deletes the specified lock on the operating system.
Parameters	pLock	handle for the lock
Return values	GOAL return status, see Chapter: GOAL status
Category	Mandatory
Condition	None

Table: goal_targetLockGet()

Prototype	GOAL_STATUS_T goal_targetLockGet(GOAL_LOCK_T *pLock, uint32_t timeout)
Description	This indication function gets a lock from the operating system.
Parameters	pLock	handle for the lock
	Timeout	behavior if it is not possible to lock the resource: >0: time for waiting on the lock in ms 0: infinite wait
Return values	GOAL return status, see Chapter: GOAL status
Category	Mandatory
Condition	None

Table: goal_targetLockPut()

Prototype	GOAL_STATUS_T goal_targetLockPut(GOAL_LOCK_T *pLock)
Description	This indication function returns a lock to the operating system.
Parameters	pLock	handle for the lock
Return values	GOAL return status, see Chapter: GOAL status
Category	Mandatory
Condition	None

Implementation guidelines

Use a lock

Create a handle for the lock:

GOAL_LOCK_T *pLockHdl = NULL;
Create a binary lock and mark the lock for the GOAL core module goal_lock:

goal_lockCreate(GOAL_LOCK_BINARY, &pLockHdl, 0, 1, GOAL_ID_LOCK);
Wait forever on a lock and set a lock:

goal_lockGet(pLockHdl, GOAL_LOCK_INFINITE);
Reset a lock:
Delete the lock:

1 Platform API
2 Implementation guidelines
- 2.1 Use a lock