유리상자 속 이야기

Using the File System Events API

파일 시스템 이벤트(File System Event) API 는 함수에 따라 크게 몇 개의 그룹으로 되어 있습니다. 볼륨과 같은 일반적인 정보와 이벤트에 대한 함수는 FSEvents 로 시작합니다. FSEventStream 로 시작하는 함수들은 새로운 이벤트 스트림을 만들고, 그 스트림을 사용하는 것 등을 담당합니다.

파일 시스템 이벤트 스트림(file system events stream) 의 생명주기는 다음과 같습니다.

1. 스트림 생성을 하기 위해서  FSEventStreamCreate 나 FSEventStreamCreateRelativeToDevice 를 호출합니다. 최초 생성시 유지 카운트(retain count)는 1 입니다. 만약 이 카운트를 증가시키고 싶다면, FSEventStreamRetain 를 호출하면 됩니다.

2. 스트림 생성을 하기 위해서  FSEventStreamCreate  나 FSEventStreamCreateRelativeToDevice 를 호출합니다. 최초 생성시 유지 카운트(retain count)는 1 입니다. 만약 이 카운트를 증가시키고 싶다면, FSEventStreamRetain 를 호출하면 됩니다.

3. FSEventStreamStart 을 호출해서, 이벤트가 전송되는 것을 시작하도록 file system events 데몬에게 알립니다.

4. 전달받은 이벤트를 처리합니다. API 는 단계 1에 정의되어있는 콜백함수의 호출을 통해서 이벤트를 전달합니다.

5. FSEventStreamStop 를 호출해서 데몬이 더 이상 이벤트를 보내지 않도록 합니다.

6. 만약 스트림을 다시 시작 해야 할 경우, 단계 3 을 수행합니다.

7. FSEventStreamUnscheduleFromRunLoop 을 호출해서 실행 루프(run loop)로부터 이벤트를 스케쥴을 하지 않습니다.

8. FSEventStreamInvalidate 를 호출해서 스트림이 유효하지 않도록 만듭니다.

9. FSEventStreamRelease  을 호출해서 스트림의 레퍼런스를 해제 시킵니다.

다음 섹션에서 좀 더 자세히 설명하도록 하겠습니다.

Adding Include Directives

file system event stream API 를 사용하기 위해서는, 아래 Core Service framework 를 include 해야 합니다.

#include <CoreServices/CoreServices.h>

그리고 컴파일을 할 때, 반드시 Core Services Framework 를 포함시켜야 합니다.  만약 Xcode 를 사용한다면 타켓(target) 에 추가시키면 됩니다. 또는 커맨드 라인이나 Makefile 을 이용한다면, 링커 플래그(liner flag)로 -framework CoreServices 를 추가시켜야 합니다.

Creating an Event Stream

file system events API 는 두 가지 타입의 event streams 를 지원합니다. 그것은 디스크 단위(per-disk) 이벤트 스트림과 호스트 단위(per-host) 이벤트 스트림 입니다. 스트림을 만들기 전에, 디스크 단위(per-host) 이벤트 스트림과 호스트 단위(per-disk) 이벤트 스트림 중 어떤 타입으로 만들지 결정해야 합니다. 각각은  FSEventStreamCreate  와  FSEventStreamCreateRelativeToDevice 를 통해 만들 수 있습니다.

호스트 단위(per-host) 이벤트 스트림은 이벤트로 구성되어 있습니다. 이 이벤트의 ID는 호스트 안에서 다른 이벤트와 연계되어 증가합니다.이 ID 값들은 한 가지 경우를 제외하고는 고유한 값이 보장됩니다. 그 한 가지 경우는 바로 Mac OS X v10.5 이후 버젼이 설치된 다른 컴퓨터에서 사용하던 디스크를 추가할 경우입니다. 이 경우 이들 볼륨의 ID 값과 충돌이 발생 할 수 있습니다. 어쨌든 새로운 이벤트의 ID 값은 모든 디스크에서 가장 큰 ID 값 다음부터 시작합니다.

디스크 단위(per-disk) 이벤트 스트림도 역시 이벤트로 구성되어 있습니다. 그러나 대조적으로 이 이벤트의 ID는 디스크 안에서 다른 이벤트와 연계되어 증가합니다. 다른 디스크의 다른 이벤트들과 어떠한 연관도 없습니다. 그렇기 때문에 여러분이 모니터링 하고 싶은 물리적으로 다른 디스크 사이에는, 각기 별도로 이벤트 스트림을 만들어야 합니다.

보통 장기적으로 계속 유지되는 소프트웨어를 만들 경우, 디스크 단위(per-disk) 스트림을 사용해서 ID 충돌이 발생하지 않도록 합니다. 반면, 큐 디렉토리 감시와 같이 일반적인 실행을 하는 동안 디렉토리 트리나 디렉토리 변화를 감시할 것이라면, 호스트 단위(per-host) 스트림을 사용하는 것이 편리합니다.

만약 root file system 에 파일을 모니터링 한다면, 두 가지 스트림 메카니즘 모두 비슷하게 동작할 것 입니다.

아래 코드조각은 이벤트 스트림을 만드는 방법을 보여주고 있습니다.

/* Define variables and create a CFArray object containing
       CFString objects containing paths to watch.
     */
    CFStringRef mypath = CFSTR("/path/to/scan");
    CFArrayRef pathsToWatch = CFArrayCreate(NULL, (const void **)&mypath, 1, NULL);
    void *callbackInfo = NULL; // could put stream-specific data here.
    FSEventStreamRef stream;
    CFAbsoluteTime latency = 3.0; /* Latency in seconds */
 
    /* Create the stream, passing in a callback */
    stream = FSEventStreamCreate(NULL,
        &myCallbackFunction,
        callbackInfo,
        pathsToWatch,
        kFSEventStreamEventIdSinceNow, /* Or a previous event ID */
        latency,
        kFSEventStreamCreateFlagNone /* Flags explained in reference */
    );

이벤트 스트림을 한번 만들면, 응용프로그램의 실행 루프(run loop)에 예약해야 합니다. 그러기 위해서 새로 생성한 스트림과 실행 루프(run loop), 그리고 실행 루프 모드(run loop mode)를 가지고  FSEventStreamScheduleWithRunLoop 를 호출합니다. 실행 루프(run loop)에 대해 더 자세히 알고 싶다면, Run Loops 를 읽어보시기 바랍니다.

만약 실행 루프(run loop)를 가지고 있지 않다면, 이 태스크의 쓰레드를 사용하면 됩니다. API 를 이용해서 쓰레드를 생성한 뒤,  CFRunLoopGetCurrent 를 호출하면, 그 쓰레드의 초기 실행 루프(run loop)가 만들어 집니다. 이후에  CFRunLoopGetCurrent 를 호출하더라도 동일한 실행 루프(run loop)가 리턴됩니다.

아래 코드조각은 stream 라는 이름의 스트림을 현재 쓰레드의 실행 루프(run loop)에 예약하는 방법을 보여 줍니다.

FSEventStreamRef stream;
 /* Create the stream before calling this. */
 FSEventStreamScheduleWithRunLoop(stream, CFRunLoopGetCurrent(),
         kCFRunLoopDefaultMode);

마지막으로  FSEventStreamStart 를 호출해서, 이벤트 스트림 설정을 마무리 합니다. 이 함수는 이벤트 스트림이 이벤트를 전송 시작하도록 하는 것입니다. 이 함수의 파라미터는 이벤트 스트림 한개입니다.

이벤트 스트림이 생성되고 예약하고 나도, 실행 루프(run loop)가 아직 시작되지 않았다면,  CFRunLoopRun . 를 호출해서 시작해 주어야 합니다.

Handling Events

이벤트 핸들러는 반드시  FSEventStreamCallback 프로토타입 형식에 일치해야 합니다. 파라미터는  FSEventStreamCallback  데이터 타입 문서에 나와 있는데로 되어 있습니다.

이벤트 핸들러는 경로 목록, 식별자 목록, 플래그 목록 이렇게 세 가지 목록을 전달 받습니다. 사실상 이것들은 이벤트 목록을 나타냅니다. 첫번째 이벤트에 대한 정보는 각 배열의 첫번째에 위치하고 있습니다. 나머지 이벤트도 동일한 방식입니다. 핸들러에서는 이 목록들을 순차적으로 순회하면서 필요한 이벤트를 처리해야 합니다.

각각의 이벤트에 대해, 지정된 경로의 디렉토리를 탐색하고 컨텐츠에 원하는 작업을 수행하십시오. 보통 지정된 경로의 디렉토리만 스캔하면 됩니다. 그러나 그렇지 않은 3가지 경우가 존재합니다.

• 만약 한 디렉토리의 하위 디렉토리에서 한 개 이상의 여러 이벤트가 거의 동시에 발생할 경우, 이벤트는 하나의 이벤트에 합쳐서 단 한번만 발생합니다. 이 경우, 이벤트의  kFSEventStreamEventFlagMustScanSubDirs  플래그가 설정되어 있습니다. 이런 이벤트를 받았을 때, 반드시 이벤트에 들어있는 경로 목록을 순환적(recursively)으로 재검색 해야 합니다. 추가적인 변경사항은 경로 리스트의 바로 다음 자식(child)이 아닐 수 있습니다.

• 만약 커널과 사용자 레벨 데몬에서 통신에러가 발생할 경우, 전달받은 이벤트는  kFSEventStreamEventFlagKernelDropped  나  kFSEventStreamEventFlagUserDropped  플래그가 설정되어 있습니다. 이 경우, 모니터링하고 있는 모든 디렉토리에 대해서 전체 스캔을 할 수 밖에 없습니다. 왜냐면 이런 상황에서는 어떤 것이 변경되었는지 알 방법이 없기 때문입니다.

• 만약 감시하고 있는 디렉토리의 루트가 삭제되거나, 이동되거나, 이름이 변경되었을 경우(혹은 상위 디렉토리가 이동되거나 이름이 변경된 경우), 그 디렉토리는 존재하지 않게 됩니다. 이 상황을 제어하기 위해서는 스트림을 만들 때,  kFSEventStreamCreateFlagWatchRoot  플래그를 사용해야 합니다. 이렇게 하면, 상황이 발생했을 때 kFSEventStreamEventFlagRootChanged  플래그가 설정된 ID 가 0 인 이벤트를 전달 받습니다. 이 경우, 디렉토리가 존재하지 않을 수 있기 때문에, 모든 디렉토리에 대해서 다시 스캔해야만 합니다.

  만약 디렉토리가 어디로 이동되었는지 알고 싶다면,  open(1)  를 이용하여 디렉토리를 열어야 합니다. 그리고 나서  fcntl(2) 에  F_GETPATH  를 넣어 호출하면 됩니다. 좀 더 자세한 정보를 보시려면  fcntl(2)  를 참고하시기 바랍니다.

• 이벤트 갯수가 2^64 개가 되면, 이벤트 id 값은 처음으로 돌아갑니다. 이렇게 되면, 이벤트의  kFSEventStreamEventFlagEventIdsWrapped  플래그가 설정 됩니다. 다행이도 가까운 미래에는 일어나지 않겠지만, 64 비트라는 숫자는 지구 표면(바다까지 포함)을 지우개 크기로 나눈 갯수가 약 2000 엑사바이트(2,000,000 기가바이트)인데, 이것을 충분히 저장할 만큼 큽니다. 그러나 이 플래그를 체크하고, 이 상황이 발생했을때, 적절한 조취를 취해야 합니다.

핸들러에서 현재 이벤트 스트림을 사용해 모니터링 하고 있는 경로의 리스트가 필요할 때가 있습니다. 이 경우  FSEventStreamCopyPathsBeingWatched  를 호출하면 리스트를 얻을 수 있습니다.

가끔 스트림의 어디쯤에 있는지 모니터링 하고 싶을 때가 있습니다. 예를들어, 이벤트를 처리 할건지 말건지 결정하기 위해서, 현재 이번트가 얼마나 오래된 것인지 알고 싶을 때가 있습니다.  callingFSEventStreamGetLatestEventId  를 호출하면, 현재의 이벤트 배치에서 가장 최신 이벤트를 찾아 낼 수 있습니다.  FSEventsGetCurrentEventId 를 호출해서 리턴되는 값과 시스템에서 가장 큰 이벤트 숫자를 비교하면 됩니다.

다음 코드조각은 매우 간단한 핸들러입니다.

void mycallback(
    ConstFSEventStreamRef streamRef,
    void *clientCallBackInfo,
    size_t numEvents,
    void *eventPaths,
    const FSEventStreamEventFlags eventFlags[],
    const FSEventStreamEventId eventIds[])
{
    int i;
    char **paths = eventPaths;
 
    // printf("Callback called\n");
    for (i=0; i<numEvents; i++) {
        int count;
        /* flags are unsigned long, IDs are uint64_t */
        printf("Change %llu in %s, flags %lu\n", eventIds[i], paths[i], eventFlags[i]);
   }
}

#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#include <dirent.h>
#include <sys/stat.h>
#include <string.h>
#include <search.h>
 
int array[] = { 1, 17, 2432, 645, 2456, 1234, 6543, 214, 3, 45, 34 };
void *dirtree;
 
static int cmp(const void *a, const void *b) {
    if (*(int *)a < *(int *)b) return -1;
    if (*(int *)a > *(int *)b) return 1;
    return 0;
}
 
void printtree(void);
 
/* Pass in a directory as an argument. */
int main(int argc, char *argv[])
{
    int i;
    for (i=0; i< sizeof(array) / sizeof(array[0]); i++) {
        void *x = tsearch(&array[i], &dirtree, &cmp);
        printf("Inserted %p\n", x);
    }
 
    printtree();
 
    void *deleted_node = tdelete(&array[2], &dirtree, &cmp);
    printf("Deleted node %p with value %d (parent node contains %d)\n",
        deleted_node, array[2], **(int**)deleted_node);
 
    for (i=0; i< sizeof(array) / sizeof(array[0]); i++) {
        void *node = tfind(&array[i], &dirtree, &cmp);
        if (node) {
            int **x = node;
            printf("Found %d (%d) at %p\n", array[i], **x, node);
        } else {
            printf("Not found: %d\n", array[i]);
        }
    }
    exit(0);
}
 
static void printme(const void *node, VISIT v, int k)
{
    const void *myvoid = *(void **)node;
    const int *myint = (const int *)myvoid;
    // printf("x\n");
    if (v != postorder && v != leaf) return;
    printf("%d\n", *myint);
}
 
void printtree(void)
{
    twalk(dirtree, &printme);
}