Critical Section doc update #298
Conversation
|
@deepikabhavnani Please review my copy edits, and make sure they didn't accidentally change the meaning of anything. |
Make copy edits, mostly for active voice and formatting.
|
@AnotherButler - Looks good, will try not to repeat same :-) |
Combine and capitalize parts of word because we're talking about the API here.
| @@ -1,3 +1,15 @@ | |||
| ## CriticalSectionLock | |||
|
|
|||
| CriticalSectionLock class provides a mechanism to access a resource uniterrupted. With the `lock` API, you can enter critical section with interrupts disabled. The `unlock` API is the exit from critical section, and the state of interrupts is restored upon exit. Nesting of critical section is supported, and interrupts are enabled only when we exit from last nested critical section. | |||
There was a problem hiding this comment.
uninterrupted or without interruption? Anything about RAII usage or scope?
| @@ -1,3 +1,18 @@ | |||
| ## CriticalSectionLock | |||
|
|
|||
| CriticalSectionLock class provides a mechanism to access a resource without interruption. With the `lock` API, you can enter critical section with interrupts disabled. The `unlock` API is the exit from critical section, and the state of interrupts is restored upon exit. Nesting of critical section is supported, and interrupts are enabled only when we exit from last nested critical section. | |||
There was a problem hiding this comment.
Do you want to remove mentions the lock and unlock since these aren't RAII and may be deprecated?
There was a problem hiding this comment.
I will keep them in 5.6 version as they are relevant. Hopefully we would deprecate by 5.7
Make minor copy edits.
| @@ -1,3 +1,17 @@ | |||
| ## CriticalSectionLock | |||
|
|
|||
| The CriticalSectionLock class provides a mechanism to access a resource without interruption. With the `lock` API, you can enter critical section with interrupts disabled. The `unlock` API is the exit from critical section, and the state of interrupts is restored upon exit. Nesting of critical section is supported, and interrupts are enabled only when we exit from last nested critical section. | |||
There was a problem hiding this comment.
Query: Who or what restores the state of interrupts upon exist? Also, who or what enables interrupts only when we exist from the last critical section?
There was a problem hiding this comment.
Destructor - restores the state of interrupts/
Destructor
| @@ -1,3 +1,17 @@ | |||
| ## CriticalSectionLock | |||
|
|
|||
| The CriticalSectionLock class provides a mechanism to access a resource without interruption. With the `lock` API, you can enter critical section with interrupts disabled. The `unlock` API is the exit from critical section, and the state of interrupts is restored upon exit. Nesting of critical section is supported, and interrupts are enabled only when we exit from last nested critical section. | |||
|
|
|||
| CriticalSectionLock class is based on RAII approach. In other words, lock is acquired in constructor and destroyed automatically when out of scope as part of destructor. We do not recommend you use CriticalSectionLock as global or a member of a class because you will enter critical section on object creation, and all interrupts will be disabled. | |||
There was a problem hiding this comment.
Query: Who or what acquires lock in the constructor? Also, who or what destroys lock automatically when it's out of scope? Also, who or what disables all interrupts when you use CriticalSectionLock as global or a member of a class?
There was a problem hiding this comment.
Constructor acquires the lock. Destructor destroys lock.
Make minor changes from passive to active voice.
|
@deepikabhavnani Please review my changes and make sure I didn't accidentally change the meaning of anything. |
Added an example to demonstrate race condition and usage of critical section api. Also updated the description for API.
https://jira.arm.com/browse/IOTMORF-1286
@AnotherButler @sg- Please review