kernel/services/data_passing/queues.html · kernel/services/data_passing/queues.rst 공식 원문 ↗

Zephyr 3.7.0 · Kernel · Data Passing

Queue

FIFO와 LIFO의 기반 object로서 임의 크기 item을 앞·뒤·중간에 배치하고 list 전체를 원자적으로 추가합니다.

Official pathkernel/services/data_passing/queues.html
Source filekernel/services/data_passing/queues.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

Reserved first word와 alloc metadata 방식, append·prepend·insert, non-constant-time remove·unique append와 ISR 제약을 설명합니다.

Base

FIFO · LIFO backend

Insert

head · tail · after

Lists

atomic append

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 4223A462FB55A01F03CF6496FECB1CCD429858DFA0F786557A5C575917F63A6B 
.. _queues:

Queues
######

A Queue in Zephyr is a kernel object that implements a traditional queue, allowing
threads and ISRs to add and remove data items of any size. The queue is similar
to a FIFO and serves as the underlying implementation for both :ref:`k_fifo
<fifos_v2>` and :ref:`k_lifo <lifos_v2>`. For more information on usage see
:ref:`k_fifo <fifos_v2>`.


Configuration Options
*********************

Related configuration options:

* None

API Reference
*************

.. doxygengroup:: queue_apis

Part 3

한국어 전문 번역

Zephyr의 Queue는 전통적인 queue를 구현한 kernel object로, thread와 ISR이 임의 크기의 data item을 추가하고 제거할 수 있습니다.

Queue는 FIFO와 비슷하며 k_fifo와 k_lifo의 기반 구현으로 사용됩니다. 일반적인 사용법은 FIFO 문서를 참고합니다.

Queue API 자체는 append, prepend, 특정 item 뒤 insert, list 단위 원자적 추가, 임의 item 제거처럼 item을 앞·뒤·중간에서 직접 조작하는 기능을 제공합니다. 일반 item은 first word를 kernel link로 예약하며 alloc 계열은 별도 metadata를 사용해 이 제약을 피합니다.

설정 옵션

이 문서에 관련 configuration option은 없습니다.

API 참고: queue_apis

K_QUEUE_DEFINE(name)

Queue를 정적으로 정의하고 초기화합니다. 정의 module 밖에서는 아래 extern declaration으로 접근합니다.

extern struct k_queue <name>;

매개변수

  • name: queue 이름
k_queue_init(queue)

Queue object를 처음 사용하기 전에 빈 상태로 초기화합니다.

매개변수

  • queue: queue 주소
k_queue_cancel_wait(queue)

Queue에서 가장 먼저 pending 중인 thread가 있으면 timeout이 끝난 것처럼 k_queue_get()에서 NULL을 받고 반환하게 합니다. k_poll() 대기 중이면 -EINTR와 K_POLL_STATE_CANCELLED 상태로 반환하며 이후 k_queue_get()도 NULL을 반환합니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
k_queue_append(queue, data)

Data item을 queue 끝에 추가합니다. Item은 word boundary에 정렬되고 첫 word는 kernel용 pointer로 예약해야 합니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
  • data: data item 주소
k_queue_alloc_append(queue, data)

Reserved first word가 없는 item을 queue 끝에 추가합니다. 호출 thread resource pool에서 임시 bookkeeping 구조체를 할당하고 item이 제거될 때 자동 해제합니다. Data 자체는 복사하지 않습니다. ISR-ok 속성이지만 allocation 조건을 만족해야 합니다.

매개변수

  • queue: queue 주소
  • data: data item 주소

반환값

  • 0: 성공
  • -ENOMEM: caller resource pool RAM 부족
k_queue_prepend(queue, data)

Data item을 queue 앞에 추가합니다. Word boundary 정렬과 kernel용 first word가 필요하며 ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
  • data: data item 주소
k_queue_alloc_prepend(queue, data)

Reserved first word가 없는 item을 resource-pool bookkeeping과 함께 queue 앞에 추가합니다. Item 제거 시 metadata를 자동 해제하고 data 자체는 복사하지 않습니다.

매개변수

  • queue: queue 주소
  • data: data item 주소

반환값

  • 0: 성공
  • -ENOMEM: caller resource pool RAM 부족
k_queue_insert(queue, prev, data)

지정한 previous item 바로 뒤에 data item을 삽입합니다. Item은 word boundary에 정렬되고 first word를 kernel용으로 비워야 합니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
  • prev: 이전 data item 주소
  • data: 삽입할 data item 주소
k_queue_append_list(queue, head, tail)

NULL로 끝나는 singly linked list 전체를 한 operation으로 queue 끝에 원자적으로 추가합니다. 각 item의 first word가 다음 item을 가리켜야 합니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
  • head: list 첫 node
  • tail: list 마지막 node

반환값

  • 0: 성공
  • -EINVAL: 잘못된 data
k_queue_merge_slist(queue, list)

sys_slist_t로 구현한 item list를 한 operation으로 원자적으로 추가합니다. 완료하면 원래 list는 empty가 됩니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
  • list: sys_slist_t object pointer

반환값

  • 0: 성공
  • -EINVAL: 잘못된 data
k_queue_get(queue, timeout)

Queue의 첫 item을 제거해 반환합니다. Item first word는 kernel reserved 영역입니다. ISR에서 호출할 때 timeout은 반드시 K_NO_WAIT여야 합니다.

매개변수

  • queue: queue 주소
  • timeout: item 대기 시간, K_NO_WAIT 또는 K_FOREVER

반환값

  • item 주소: 성공
  • NULL: 기다리지 않았거나 timeout 만료
k_queue_remove(queue, data)

지정 item을 queue에서 찾아 제거합니다. 내부 sys_slist_find_and_remove에 의존하므로 constant-time operation이 아닙니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
  • data: 제거할 item 주소

반환값

  • true: item 제거됨
  • false: item을 찾지 못함
k_queue_unique_append(queue, data)

같은 item이 아직 없을 때만 queue 끝에 추가합니다. Membership 검색이 sys_slist_is_node_in_list에 의존하므로 constant-time operation이 아닙니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소
  • data: 추가할 item 주소

반환값

  • true: item 추가됨
  • false: 이미 존재하여 추가하지 않음
k_queue_is_empty(queue)

Queue에 data가 있는지 확인합니다. 다른 thread도 읽는다면 반환 직후 상태가 달라질 수 있으므로 synchronization 판정으로 사용하면 안 됩니다. ISR에서도 호출할 수 있습니다.

매개변수

  • queue: queue 주소

반환값

  • non-zero: queue가 비어 있음
  • 0: data가 있음
k_queue_peek_head(queue)

Head item을 제거하지 않고 반환합니다.

매개변수

  • queue: queue 주소

반환값

  • head item: data가 있을 때
  • NULL: queue가 비어 있을 때
k_queue_peek_tail(queue)

Tail item을 제거하지 않고 반환합니다.

매개변수

  • queue: queue 주소

반환값

  • tail item: data가 있을 때
  • NULL: queue가 비어 있을 때

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.