정의 슬롯¶

C API를 사용하여 :ref:`모듈 객체 <moduleobjects>`와 :ref:`클래스 <creating-heap-types>`를 정의하려면 슬롯 배열을 사용할 수 있습니다. 이는 본질적으로 생성될 객체의 기능을 설명하는 키-값 쌍입니다. 이 방식은 데이터를 런타임에 사용되는 구조체로부터 분리하여, CPython – 및 기타 Python C API 구현체 – 가 하위 호환성을 깨뜨리지 않고 구조체를 업데이트할 수 있도록 합니다.

이 섹션에서는 슬롯에 대해 일반적으로 설명합니다. 객체별 동작 및 슬롯 값에 대해서는 슬롯을 적용하는 함수 문서를 참조하십시오:

타입용 PyType_FromSlots();
모듈용 PyModule_FromSlotsAndSpec() 및 Extension export hook.

슬롯이 적용하는 함수에 슬롯이 전달되면, 해당 함수는 슬롯 배열이나 그것이 가리키는 데이터(재귀적으로)를 수정하지 않습니다. 함수가 끝난 후 호출자는 :c:macro:`PySlot_STATIC`으로 명시적으로 표시된 데이터를 제외하고, 배열과 그것이 가리키는 데이터(재귀적으로)를 수정하거나 해제할 수 있습니다.

다르게 문서화되지 않은 한, 동일한 ID를 가진 여러 개의 슬롯(sl_id)은 단일 슬롯 배열에 나타날 수 없습니다.

Added in version 3.15: Slot arrays generalize an earlier way of defining objects: using PyType_Spec with PyType_Slot for types, and PyModuleDef with PyModuleDef_Slot for modules. The earlier API is soft deprecated; there are no plans to remove it.

슬롯 배열의 항목은 다음 구조를 사용합니다:

type PySlot¶

상의 안정 ABI (모든 멤버 포함) 버전 3.15 이후로.

슬롯 배열의 한 항목입니다. 다음과 같이 정의됩니다:

typedef struct {
    uint16_t sl_id;
    uint16_t sl_flags;
    uint32_t _reserved;  // 반드시 0이어야 함
    union {
        void *sl_ptr;
        void (*sl_func)(void);
        Py_ssize_t sl_size;
        int64_t sl_int64;
        uint64_t sl_uint64;
    };
} PySlot;

uint16_t sl_id¶

아래에서 설명된 값들 중에서 선택된 슬롯 ID입니다.

아래 공통 슬롯 ID 에 문서화된 Py_slot_* 값들;
모듈용 Py_mod_* 값들로, Module definition 에 문서화되어 있습니다;
타입용 값들로, Type slot IDs 에 문서화되어 있습니다.

sl_id 값이 0인 (Py_slot_end) 가 슬롯 배열의 끝을 표시합니다.

void *sl_ptr¶

void (*sl_func)(void)¶

Py_ssize_t sl_size¶

int64_t sl_int64¶

uint64_t sl_uint64¶

슬롯의 데이터입니다. 이 멤버들은 익명 유니온의 일부이며, 사용할 멤버는 슬롯 ID가 요구하는 데이터 유형(데이터 포인터, 함수 포인터, 크기, 부호 있는 또는 부호 없는 정수)에 따라 달라집니다.

특정 슬롯 ID에 대해 달리 문서화된 경우가 아니라면, 포인터(즉, sl_ptr 및 sl_func)는 NULL일 수 없습니다.

uint16_t sl_flags¶

다음 플래그 중 0개 이상을 OR 연산한 값입니다:

PySlot_STATIC¶

상의 안정 ABI 버전 3.15 이후로.

슬롯이 가리키는 모든 데이터는 정적으로 할당되고 상수입니다. 따라서 인터프리터는 정보를 복사할 필요가 없습니다.

이 플래그는 함수 포인터에 대해 암시적으로 적용됩니다.

이 플래그는 슬롯이 가리키는 데이터에 “간접적으로” 적용되는 경우에도 마찬가지입니다. 예외는 Py_slot_subslots 을 통해 중첩된 슬롯이며, 이 경우 자체적인 PySlot_STATIC 플래그를 가질 수 있습니다. 예를 들어, Py_tp_members 슬롯에 적용되어 PyMemberDef 구조체의 배열을 가리키는 경우, 전체 배열과 그 요소들의 이름 및 독스트링은 정적이고 상수여야 합니다.

PySlot_INTPTR¶

상의 안정 ABI 버전 3.15 이후로.

데이터는 sl_ptr 에 저장됩니다. CPython은 이를 적절한 유형으로 캐스팅합니다.

이 플래그는 이전 버전의 PyType_Slot 및 PyModuleDef_Slot 구조체에서 포팅할 때 간소화할 수 있습니다.

PySlot_OPTIONAL¶

상의 안정 ABI 버전 3.15 이후로.

슬롯 ID를 모르는 경우, 인터프리터는 실패하는 대신 해당 슬롯을 무시해야 합니다.

예를 들어, Python 3.16이 새로운 슬롯 ID,attr을 가진 새로운 기능을 추가하는 경우, 해당 슬롯은 Python 3.15가 무시하도록 :c:macro:`!PySlot_OPTIONAL`로 표시될 수 있습니다.

“선택적”이라는 것은 알 수 없는 슬롯 ID에만 적용된다는 점에 유의하십시오. 이 플래그는 알려진 슬롯의 유효하지 않은 값을 건너뛰게 만들지 않습니다.

Added in version 3.15.

편의 매크로¶

PySlot_DATA(name, value)¶

PySlot_FUNC(name, value)¶

PySlot_SIZE(name, value)¶

PySlot_INT64(name, value)¶

PySlot_UINT64(name, value)¶

PySlot_STATIC_DATA(name, value)¶

상의 안정 ABI 버전 3.15 이후로.

sl_id 및 특정 유니온 멤버 세트를 사용하여 PySlot 구조체를 정의하기 위한 편의 매크로입니다.

PySlot_STATIC_DATA 는 PySlot_STATIC 플래그를 설정합니다. 다른 매크로는 플래그를 설정하지 않습니다.

참고: 이 매크로들은 지정된 초기화자(designated initializers) 를 사용합니다. 이는 C++에서 2020년 표준 버전에 추가된 C 언어 기능입니다. 코드가 C++11 이하와 호환되어야 하는 경우, 대신 PySlot_PTR 을 사용하십시오.

다음과 같이 정의됩니다:

#define PySlot_DATA(NAME, VALUE) \
   {.sl_id=NAME, .sl_ptr=(void*)(VALUE)}

#define PySlot_FUNC(NAME, VALUE) \
   {.sl_id=NAME, .sl_func=(VALUE)}

#define PySlot_SIZE(NAME, VALUE) \
   {.sl_id=NAME, .sl_size=(VALUE)}

#define PySlot_INT64(NAME, VALUE) \
   {.sl_id=NAME, .sl_int64=(VALUE)}

#define PySlot_UINT64(NAME, VALUE) \
   {.sl_id=NAME, .sl_uint64=(VALUE)}

#define PySlot_STATIC_DATA(NAME, VALUE) \
   {.sl_id=NAME, .sl_flags=PySlot_STATIC, .sl_ptr=(VALUE)}

Added in version 3.15.

PySlot_END¶

상의 안정 ABI 버전 3.15 이후로.

PySlot 배열의 끝을 표시하는 편의 매크로입니다.

다음과 같이 정의됩니다:

#define PySlot_END {0}

Added in version 3.15.

PySlot_PTR(name, value)¶

PySlot_PTR_STATIC(name, value)¶

상의 안정 ABI 버전 3.15 이후로.

C++11과 호환되는 코드를 사용하는 편의 매크로입니다. 이 버전의 C++는 리터럴에 임의의 유니온 멤버를 설정하는 것을 허용하지 않으므로, 대신 이 매크로들은 PySlot_INTPTR 플래그를 설정하고 값을 (void*) 로 캐스팅합니다.

다음과 같이 정의됩니다:

#define PySlot_PTR(NAME, VALUE) \
   {NAME, PySlot_INTPTR, {0}, {(void*)(VALUE)}}

#define PySlot_PTR_STATIC(NAME, VALUE) \
   {NAME, PySlot_INTPTR|Py_SLOT_STATIC, {0}, {(void*)(VALUE)}}

Added in version 3.15.

공통 슬롯 ID¶

다음 슬롯 ID는 타입 정의와 모듈 정의 모두에 사용될 수 있습니다.

Py_slot_end¶: 상의 안정 ABI 버전 3.15 이후로.
슬롯 배열의 끝을 표시합니다. 0으로 정의됩니다.

Added in version 3.15.

Py_slot_subslots¶

상의 안정 ABI 버전 3.15 이후로.

중첩된 슬롯 배열입니다.

값 (sl_ptr) 은 PySlot 구조체의 배열을 가리켜야 합니다. 배열 내의 슬롯(0 ID 종료자 직전까지)은, :c:macro:`!Py_slot_subslots`가 나타나는 지점의 현재 슬롯 배열에 삽입된 것처럼 처리될 것입니다.

슬롯 중첩 깊이는 5단계로 제한됩니다. 이 제한은 향후 해제될 수 있습니다.

Added in version 3.15.

Py_slot_invalid¶

상의 안정 ABI 버전 3.15 이후로.

예약됨; 항상 알 수 없는 슬롯 ID로 처리됩니다. UINT16_MAX (0xFFFF)로 정의됩니다.

PySlot_OPTIONAL 플래그와 함께 사용될 때, 아무런 효과가 없는 슬롯을 정의합니다. 플래그가 없는 경우, 이 ID를 가진 슬롯을 처리하면 실패합니다.

Added in version 3.15.

정의 슬롯¶

편의 매크로¶

공통 슬롯 ID¶

분실물 보관소