Skip to main content

gbase

Overview​

gbase는 Grap 엔진 전체에서 사용하는 최하위(Foundation) 레벨 라이브러리이다.
이 모듈은 모든 상위 모듈(gcore, ghost, ginter, grender, app)이 공통적으로 의존할 수 있는 최소 공통 기반 기능을 제공한다.

gbase의 주요 목적은 다음과 같다.

  • 엔진 전체에서 사용하는 기본 타입 정의
  • 타입 안정성을 보장하는 ID 시스템 제공
  • 범용적인 매크로 및 컴파일러 attribute 래퍼 제공
  • 범용 유틸리티 제공
  • 플랫폼 및 OS 의존성 제거

gbase는 엔진 구조에서 가장 아래 레이어에 위치하며, 다음과 같은 특징을 가진다.

  • Header-only 라이브러리
  • 플랫폼 독립성 유지
  • 최소 의존성 설계
  • 컴파일 타임 유틸리티 중심 설계
  • 상위 모듈에 대한 의존성 없음

gbase는 Grap 프로젝트에서 다음과 같은 기반 기능을 제공한다.

  • Strong typed identifier 시스템
  • enum class 기반 bitmask 연산 지원
  • 연속 메모리 view 타입
  • Scope 기반 RAII 유틸리티
  • 컴파일러 attribute 및 전처리 매크로
  • 타입 변환 및 안전성 유틸리티

SRS (Software Requirements Specification)

Purpose​

본 문서는 Grap 엔진의 기반 라이브러리인 gbase의 기능적 요구사항과 비기능적 요구사항을 정의한다.

gbase는 엔진의 다른 모든 모듈에서 공통적으로 사용하는 기본 타입 및 유틸리티 기능을 제공하는 것을 목표로 한다.

Scope​

gbase는 다음 기능을 제공한다.

  • Strong ID 시스템
  • enum class bitmask 연산 지원
  • 배열 view 타입
  • Scope 기반 RAII 유틸리티
  • 매크로 및 컴파일러 attribute 래퍼
  • 타입 유틸리티

Functional Requirements​

FR-1 Strong Typed Identifier​

시스템은 서로 다른 ID 타입 간의 혼용을 방지해야 한다.
각 ID는 고유한 타입을 가지며, 다른 ID 타입과 암묵적으로 변환될 수 없어야 한다.

FR-2 Enum Bitmask Support​

enum class 타입에 대해 안전한 bitmask 연산을 지원해야 한다.
사용자는 특정 enum 타입에 대해 bitmask 연산을 활성화할 수 있어야 한다.

FR-3 Span View​

연속 메모리 블록을 안전하게 참조할 수 있는 view 타입을 제공해야 한다.
해당 타입은 메모리를 소유하지 않으며 기존 배열 또는 버퍼를 참조한다.

FR-4 Scope Utilities​

Scope 종료 시 실행되는 RAII 기반 유틸리티를 제공해야 한다.
다음과 같은 실행 조건을 지원해야 한다.

  • Scope 종료 시 실행
  • 예외 발생 시 실행
  • 정상 종료 시 실행

FR-5 Variant Visitor Helper​

std::variant 사용 시 간결한 visitor 구성을 지원하는 helper를 제공해야 한다.

Non Functional Requirements​

NFR-1 Header-only Library​

gbase는 별도의 소스 파일 없이 헤더만으로 구성된 라이브러리여야 한다.

NFR-2 Minimal Dependencies​

gbase는 표준 라이브러리 외의 외부 라이브러리에 의존하지 않아야 한다.

NFR-3 Platform Independence​

플랫폼 및 OS 의존 기능을 포함하지 않아야 한다.

NFR-4 Compile-time Safety​

가능한 많은 검증을 컴파일 타임에 수행하도록 설계되어야 한다.

SDS (Software Design Specification)

Design Goals​

gbase는 다음 설계 목표를 따른다.

  • 타입 안정성 강화
  • 최소 오버헤드 구현
  • 컴파일 타임 중심 설계
  • 상위 모듈과의 완전한 독립성

Module Structure​

gbase는 다음 서브시스템으로 구성된다.

types​

기본 타입 및 타입 유틸리티를 제공한다.

주요 기능

  • 기본 정수 타입 alias
  • byte 타입 래퍼
  • span view
  • enum bitmask helper

id_sys​

타입 안정성을 보장하는 ID 시스템을 제공한다.

주요 기능

  • StrongId 타입
  • IdTag 기반 ID 구분
  • 공용 ID 타입 정의

macro​

매크로 및 컴파일러 attribute 관련 기능을 제공한다.

주요 기능

  • assert 매크로
  • 컴파일러 attribute 래퍼
  • 전처리 매크로 helper
  • static_assert wrapper

utility​

범용 유틸리티 기능을 제공한다.

주요 기능

  • 복사 금지 타입
  • 이동 금지 타입
  • Scope 기반 RAII 유틸리티
  • variant visitor helper
  • 안전한 타입 변환
  • defer 유틸리티

Architecture

Layer Position​

gbase는 Grap 엔진 아키텍처에서 최하위 레이어에 위치한다.

모든 상위 모듈은 gbase에 의존할 수 있지만, gbase는 어떤 상위 모듈에도 의존하지 않는다.

Dependency Model​

gbase 내부 서브시스템 간 의존성은 다음 규칙을 따른다.

  • types는 가장 하위 레이어이다.
  • macro는 types에 의존할 수 있다.
  • id_sys는 types에 의존할 수 있다.
  • utility는 types 및 macro에 의존할 수 있다.

서브시스템 간 순환 의존성은 허용되지 않는다.

Directory Structure​

gbase의 디렉토리 구조는 다음과 같다.

  • 루트에는 빌드 설정과 umbrella header가 위치한다.
  • 각 기능은 별도의 서브시스템 디렉토리로 분리된다.
  • 테스트 코드는 별도의 테스트 디렉토리에 위치한다.

API

StrongId​

타입 안전 ID를 제공하는 템플릿 클래스이다.

각 ID는 Tag 타입과 내부 정수 타입을 기반으로 정의된다.

IdTag​

ID 타입을 구분하기 위한 태그 구조체이다.

StrongId와 함께 사용된다.

Span​

연속된 메모리 영역을 참조하기 위한 view 타입이다.

메모리 소유권은 가지지 않는다.

enable_bitmask_operators​

특정 enum 타입에 대해 bitmask 연산을 활성화하기 위한 trait이다.

Scope Utilities​

Scope 기반 실행 유틸리티를 제공한다.

  • scope_exit
  • scope_fail
  • scope_success

GBASE_DEFER​

Scope 종료 시 실행되는 defer 기능을 제공하는 매크로이다.

Overloaded​

std::variant visitor 구성을 단순화하는 helper 구조체이다.

narrow_cast​

타입 변환 시 narrowing 여부를 검사하는 유틸리티이다.