Repository navigation
Referência da API pública
A API pública do CPU Reader está definida no arquivo:
include/cpu.h
Ela fornece funções para inicialização, coleta de informações da CPU, cálculo de utilização, leitura de temperatura e clock, consulta de processos ativos, gerenciamento de memória e tratamento de erros.
A interface principal é:
int cpu_init(void);
void cpu_cleanup(void);
cpu_info_t *cpu_get_info(void);
float cpu_get_usage(void);
int cpu_usage_context_init(cpu_usage_context_t *context);
void cpu_usage_context_cleanup(cpu_usage_context_t *context);
float cpu_get_usage_context(cpu_usage_context_t *context);
float cpu_get_temperature(void);
float cpu_get_clock_speed(void);
int cpu_get_active_processes(void);
void cpu_free_info(cpu_info_t *info);
cpu_error_t cpu_get_last_error_code(void);
const char *cpu_get_last_error(void);Inicializa a biblioteca.
int cpu_init(void);Retorno:
0 sucesso
valor diferente de 0 erro
Exemplo:
if (cpu_init() != 0) {
fprintf(stderr, "Falha ao inicializar CPU Reader\n");
return 1;
}A inicialização deve ocorrer antes das operações que dependem do estado interno da biblioteca.
Finaliza o uso da biblioteca e libera recursos internos associados ao ciclo de vida da aplicação.
void cpu_cleanup(void);Exemplo:
cpu_init();
/* utilização da API */
cpu_cleanup();A função não recebe argumentos e não retorna valor.
Obtém informações gerais sobre o processador.
cpu_info_t *cpu_get_info(void);A função pode retornar informações como:
- modelo;
- frequência;
- flags;
- processadores lógicos;
- threads online;
- processos ativos;
- temperatura, quando disponível.
O resultado é armazenado em uma estrutura alocada dinamicamente. Portanto, o chamador é responsável por liberar a memória utilizando cpu_free_info().
Exemplo:
cpu_info_t *info = cpu_get_info();
if (info == NULL) {
fprintf(stderr, "Erro: %s\n", cpu_get_last_error());
return 1;
}
/* utilização dos dados */
cpu_free_info(info);Libera a estrutura retornada por cpu_get_info().
void cpu_free_info(cpu_info_t *info);Uso correto:
cpu_info_t *info = cpu_get_info();
if (info != NULL) {
/* utiliza info */
cpu_free_info(info);
}Não se deve chamar free() diretamente sobre a estrutura retornada pela API. A função cpu_free_info() deve ser utilizada para manter o gerenciamento de memória encapsulado na biblioteca.
Obtém o percentual agregado de utilização da CPU.
float cpu_get_usage(void);Retorno esperado:
0.0 → CPU sem utilização
100.0 → CPU totalmente utilizada
Em caso de falha na leitura dos dados necessários, a função retorna:
-1.0fO cálculo é realizado utilizando duas leituras dos contadores disponíveis em /proc/stat.
Exemplo:
float usage = cpu_get_usage();
if (usage < 0.0f) {
fprintf(stderr, "Erro: %s\n", cpu_get_last_error());
} else {
printf("CPU: %.2f%%\n", usage);
}O CPU Reader também fornece uma API baseada em cpu_usage_context_t.
Essa abordagem permite manter estados independentes para diferentes consumidores da biblioteca.
Inicializa um contexto.
int cpu_usage_context_init(cpu_usage_context_t *context);Exemplo:
cpu_usage_context_t context;
if (cpu_usage_context_init(&context) != 0) {
fprintf(stderr, "Falha ao inicializar contexto\n");
return 1;
}Calcula o uso utilizando o contexto fornecido.
float cpu_get_usage_context(cpu_usage_context_t *context);Exemplo:
float usage = cpu_get_usage_context(&context);
if (usage >= 0.0f) {
printf("CPU: %.2f%%\n", usage);
}Libera o estado associado ao contexto.
void cpu_usage_context_cleanup(cpu_usage_context_t *context);Uso:
cpu_usage_context_cleanup(&context);O ciclo completo é:
cpu_usage_context_init()
↓
cpu_get_usage_context()
↓
cpu_get_usage_context()
↓
...
↓
cpu_usage_context_cleanup()
Obtém a temperatura da CPU quando existe um sensor compatível disponível através do sysfs.
float cpu_get_temperature(void);Exemplo:
float temperature = cpu_get_temperature();
if (temperature < 0.0f) {
fprintf(stderr, "Temperatura indisponível\n");
} else {
printf("Temperatura: %.2f °C\n", temperature);
}A disponibilidade dessa informação depende do hardware, do kernel e dos sensores expostos pelo sistema.
Portanto, uma aplicação não deve assumir que a temperatura estará sempre disponível.
Obtém a velocidade atual do clock da CPU.
float cpu_get_clock_speed(void);A implementação tenta primeiro consultar:
/sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq
Caso essa interface não esteja disponível, utiliza como fallback o primeiro valor cpu MHz encontrado em /proc/cpuinfo.
Exemplo:
float clock = cpu_get_clock_speed();
if (clock < 0.0f) {
fprintf(stderr, "Clock indisponível\n");
} else {
printf("Clock: %.2f MHz\n", clock);
}Obtém a quantidade de processos ativos informada pelo sistema.
int cpu_get_active_processes(void);A implementação utiliza /proc/loadavg como fonte de dados.
Exemplo:
int processes = cpu_get_active_processes();
if (processes < 0) {
fprintf(stderr, "Erro: %s\n", cpu_get_last_error());
} else {
printf("Processos ativos: %d\n", processes);
}Retorna o código associado ao último erro registrado pela biblioteca.
cpu_error_t cpu_get_last_error_code(void);Os códigos disponíveis incluem:
CPU_ERROR_INVALID_ARGUMENT
CPU_ERROR_FILE_OPEN
CPU_ERROR_PARSE
CPU_ERROR_MEMORY
CPU_ERROR_UNSUPPORTEDExemplo:
cpu_error_t error = cpu_get_last_error_code();
if (error != 0) {
printf("Código do erro: %d\n", error);
}Retorna uma mensagem textual relacionada ao último erro.
const char *cpu_get_last_error(void);Exemplo:
cpu_info_t *info = cpu_get_info();
if (info == NULL) {
fprintf(
stderr,
"CPU Reader: %s\n",
cpu_get_last_error()
);
}O erro deve ser consultado imediatamente após uma operação que falhou, pois o estado é global e pode ser alterado por chamadas posteriores. O mecanismo atual não é thread-safe.
Um programa mínimo utilizando a API pode seguir este modelo:
#include <stdio.h>
#include "cpu.h"
int main(void)
{
if (cpu_init() != 0) {
fprintf(stderr, "Erro ao inicializar: %s\n",
cpu_get_last_error());
return 1;
}
cpu_info_t *info = cpu_get_info();
if (info == NULL) {
fprintf(stderr, "Erro ao obter informações: %s\n",
cpu_get_last_error());
cpu_cleanup();
return 1;
}
float usage = cpu_get_usage();
float temperature = cpu_get_temperature();
float clock = cpu_get_clock_speed();
int processes = cpu_get_active_processes();
printf("CPU Reader\n");
printf("==========\n");
printf("Uso: %.2f%%\n", usage);
printf("Temperatura: %.2f °C\n", temperature);
printf("Clock: %.2f MHz\n", clock);
printf("Processos ativos: %d\n", processes);
cpu_free_info(info);
cpu_cleanup();
return 0;
}Ao utilizar a API, recomenda-se:
- Inicializar a biblioteca antes das operações.
- Verificar os valores de retorno das funções.
- Verificar
cpu_get_last_error()após uma falha. - Liberar estruturas obtidas por
cpu_get_info()comcpu_free_info(). - Finalizar a biblioteca com
cpu_cleanup(). - Não assumir que temperatura ou clock estarão disponíveis em todos os sistemas.
- Evitar utilizar o mecanismo global de erros simultaneamente a partir de múltiplas threads.
- Utilizar
cpu_usage_context_tquando forem necessários estados independentes para cálculo de utilização.
┌──────────────┐
│ cpu_init() │
└──────┬───────┘
↓
┌──────────────────────┐
│ Consultar informações│
│ da CPU │
└──────┬───────────────┘
↓
┌──────────────────────┐
│ Verificar retorno │
└──────┬───────────────┘
↓
┌───┴────┐
│ │
OK ERRO
│ │
↓ ↓
usar dados obter erro
│ │
↓ │
liberar │
│ │
└────┬───┘
↓
┌────────────────┐
│ cpu_cleanup() │
└────────────────┘
Esta API constitui a camada pública do CPU Reader. A implementação interna permanece organizada nos módulos de informação da CPU, cálculo de utilização e demais componentes do projeto.