ppos/lib/queue.h

   1 // PingPongOS - PingPong Operating System
   2 // Prof. Carlos A. Maziero, DINF UFPR
   3 // Versão 2.0 -- Junho de 2025
   4
   5 // ATENÇÃO: ESTE ARQUIVO NÃO DEVE SER ALTERADO;
   6 // ALTERAÇÕES SERÃO DESCARTADAS NA CORREÇÃO.
   7
   8 /*
   9 TAD fila genérica de ponteiros, que armazena itens de tipo "void *".
  10 A fila mantém um iterador que aponta para um item da fila (ou para NULL).
  11 O iterador pode ser ajustado usando as funções queue_head() e queue_next()
  12 e ter seu item consultado com a função queue_item(). Inicialmente o iterador
  13 aponta para o começo da fila.
  14 */
  15
  16 #ifndef __QUEUE__
  17 #define __QUEUE__
  18
  19 #include <stdbool.h>
  20
  21 // códigos de retorno das funções
  22 #ifndef ERROR
  23 #define ERROR -1
  24 #define NOERROR 0
  25 #endif
  26
  27 // ponteiro nulo
  28 #ifndef NULL
  29 #define NULL ((void *)0)
  30 #endif
  31
  32 // struct que representa uma fila; este é um struct "opaco",
  33 // que deve ser redefinido completamente em queue.c
  34 struct queue_t;
  35
  36 // Cria uma fila inicialmente vazia.
  37 // Retorno: ponteiro p/ a nova fila
  38 //          NULL se houver erro
  39 struct queue_t *queue_create();
  40
  41 // Destroi uma fila, liberando a memória alocada por ela.
  42 // IMPORTANTE: os itens apontados pela fila NÃO devem ser liberados,
  43 // pois a aplicação que os criou e pôs na fila é responsável por eles.
  44 // Retorno: NOERROR ou ERROR (se a fila não existir)
  45 int queue_destroy(struct queue_t *queue);
  46
  47 // Adiciona um item no fim da fila; ajusta o iterador para ele
  48 // se for o primeiro item (ou seja, se a fila estiver vazia).
  49 // Retorno: NOERROR ou ERROR (se fila ou item não existir)
  50 int queue_add(struct queue_t *queue, void *item);
  51
  52 // Retira da fila o item com o valor indicado; se o item estiver
  53 // em mais de uma posição da fila, retira apenas da primeira posição
  54 // encontrada; se o item estiver apontado pelo iterador, este avança
  55 // para o próximo item da fila (ou para NULL, se for o último).
  56 // Retorno: NOERROR ou ERROR (não encontrou ou outro erro).
  57 int queue_del(struct queue_t *queue, void *item);
  58
  59 // Informa se o item indicado está na fila.
  60 // Retorno: true/false (error: false).
  61 bool queue_has(struct queue_t *queue, void *item);
  62
  63 // Informa o número de itens na fila.
  64 // Retorno: número de itens na fila (>= 0)
  65 //          ERROR se a fila não existir
  66 int queue_size(struct queue_t *queue);
  67
  68 // Põe o iterador no início da fila.
  69 // Retorno: ptr para o item apontado pelo iterador
  70 //          NULL se a fila estiver vazia ou não existir
  71 void *queue_head(struct queue_t *queue);
  72
  73 // Avança o iterador ao próximo item na fila.
  74 // Retorno: ptr para o item apontado pelo iterador após avançar
  75 //          NULL se o iterador passou do último item da fila
  76 //          NULL se a fila estiver vazia ou não existir
  77 void *queue_next(struct queue_t *queue);
  78
  79 // Informa o item atualmente sob o iterador na fila.
  80 // Retorno: ptr para o item apontado pelo iterador
  81 //          NULL se a fila estiver vazia ou não existir
  82 //          NULL se o iterador passou do fim da fila
  83 void *queue_item(struct queue_t *queue);
  84
  85 // Imprime os elementos de uma fila; a função externa "func"
  86 // deve ser chamada para imprimir cada item.
  87 // Exemplos de saída, com name == "Frutas":
  88 // Frutas: [ banana pera ameixa uva ] (4 itens)
  89 // Frutas: [ ] (0 itens)
  90 // Frutas: undef   se queue == NULL
  91 // Frutas: [ undef undef undef ] (3 itens)  se func == NULL
  92 void queue_print(char *name, struct queue_t *queue, void(func)(void *));
  93
  94 #endif