User guide: message queues and notifications

Open
  • Is something wrong?
#113 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
83/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
c
Domain
documentation

Research direction

Read the API contracts in include/emb/msgq.h and include/emb/notify.h, the behavior tests in tests/conformance/test_msgq.c and test_notify.c, and SPEC-007 and SPEC-006. Use examples/hello_app/main.c and docs/user/synchronization.md and tasks.md for examples and style. Add docs/user/communication.md, link it from docs/user/index.md, and confirm the strict docs build and every example compile.

Written by the indexing model from the issue text.

Description

documentation good first issue

Goal

Write the user-guide page on message queues and notifications: docs/user/communication.md. The guide has pages on threads, synchronization and interrupts, but none yet on how threads pass data.

What exists

  • The API: include/emb/msgq.h and include/emb/notify.h, with a contract comment on every function.
  • The design: SPEC-007 (message queues) and SPEC-006 (notifications).
  • The tests show every behaviour: tests/conformance/test_msgq.c, test_notify.c.
  • An example that uses a queue: examples/hello_app/main.c.
  • The existing pages, for tone and length: docs/user/synchronization.md, docs/user/tasks.md.

What the page should cover

  • Message queues: copy by value, EMB_MSGQ_DEFINE, send and receive with timeouts, send to the front, peek, use from an interrupt with EMB_NO_WAIT.
  • Direct-to-thread notifications: when to use them instead of a semaphore or a queue.
  • Bindings: a semaphore, event flags or a queue notifying a thread.
  • A short, complete example for each, checked by building it.

Done when

  • docs/user/communication.md exists and is in the toctree of docs/user/index.md.
  • The strict docs build passes (python tools/docs/build.py, see docs/engineering/documentation.md).
  • Every code example compiles; say in the PR how you checked.
Dominant language
C
Stars
1
Forks
1
Avg merge
14h 21m
Merged PRs (30d)
125

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from EmbLinkOs/EmbLinkRTOS

All issues in EmbLinkOs/EmbLinkRTOS

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.