harmony 鸿蒙Standard Library

2022-08-09
浏览 (923)

Standard Library

The OpenHarmony kernel uses the musl libc library that supports the Portable Operating System Interface (POSIX). You can develop components and applications working on the kernel based on the POSIX.

Standard Library API Framework

Figure 1 POSIX framework

The musl libc library supports POSIX standards. The OpenHarmony kernel adapts the related system call APIs to implement external functions.

For details about the APIs supported by the standard library, see the API document of the C library, which also covers the differences between the standard library and the POSIX standard library.

Development Example

Example Description

In this example, the main thread creates THREAD_NUM child threads. Once a child thread is started, it enters the standby state. After the main thread successfully wakes up all child threads, they continue to execute until the lifecycle ends. The main thread uses the pthread_join method to wait until all child threads are executed.

Sample Code

The sample code can be compiled and verified in ./kernel/liteos_a/testsuites/kernel/src/osTest.c. The ExamplePosix function is called in TestTaskEntry.

The sample code is as follows:

#include <stdio.h>
#include <unistd.h>
#include <pthread.h>

#define THREAD_NUM 3
int g_startNum = 0; /* Number of threads to start */
int g_wakenNum = 0; /* Number of threads to wake up */

struct testdata {
    pthread_mutex_t mutex;
    pthread_cond_t cond;
} g_td;

/* Entry function of the child thread */
static VOID *ChildThreadFunc(VOID *arg)
{
    int rc;
    pthread_t self = pthread_self();

    /* Acquire a mutex. */
    rc = pthread_mutex_lock(&g_td.mutex);
    if (rc != 0) {
        dprintf("ERROR:take mutex lock failed, error code is %d!\n", rc);
        goto EXIT;
    }

    /* The value of g_startNum is increased by 1. The value indicates the number of child threads that have acquired a mutex. */
    g_startNum++;

     /* Wait for the cond variable. */
    rc = pthread_cond_wait(&g_td.cond, &g_td.mutex);
    if (rc != 0) {
        dprintf("ERROR: pthread condition wait failed, error code is %d!\n", rc);
        (void)pthread_mutex_unlock(&g_td.mutex);
        goto EXIT;
    }

    /* Attempt to acquire a mutex, which is failed in normal cases. */
    rc = pthread_mutex_trylock(&g_td.mutex);
    if (rc == 0) {
        dprintf("ERROR: mutex gets an abnormal lock!\n");
        goto EXIT;
    }

    /* The value of g_wakenNum is increased by 1. The value indicates the number of child threads that have been woken up by the cond variable. */
    g_wakenNum++;

    /* Release a mutex. */
    rc = pthread_mutex_unlock(&g_td.mutex);
    if (rc != 0) {
        dprintf("ERROR: mutex release failed, error code is %d!\n", rc);
        goto EXIT;
    }
EXIT:
    return NULL;
}

static int ExamplePosix(VOID)
{
    int i, rc;
    pthread_t thread[THREAD_NUM];

    /* Initialize the mutex. */
    rc = pthread_mutex_init(&g_td.mutex, NULL);
    if (rc != 0) {
        dprintf("ERROR: mutex init failed, error code is %d!\n", rc);
        goto ERROROUT;
    }

    /* Initialize the cond variable. */
    rc = pthread_cond_init(&g_td.cond, NULL);
    if (rc != 0) {
        dprintf("ERROR: pthread condition init failed, error code is %d!\n", rc);
        goto ERROROUT;
    }

    /* Create child threads in batches. */
    for (i = 0; i < THREAD_NUM; i++) {
        rc = pthread_create(&thread[i], NULL, ChildThreadFunc, NULL);
        if (rc != 0) {
            dprintf("ERROR: pthread create failed, error code is %d!\n", rc);
            goto ERROROUT;
        }
    }
    dprintf("pthread_create ok\n");

    /* Wait until all child threads obtain a mutex. */
    while (g_startNum < THREAD_NUM) {
        usleep(100);
    }

    /* Acquire a mutex and block all threads using pthread_cond_wait. */
    rc = pthread_mutex_lock(&g_td.mutex);
    if (rc != 0) {
        dprintf("ERROR: mutex lock failed, error code is %d\n", rc);
        goto ERROROUT;
    }

    /* Release the mutex. */
    rc = pthread_mutex_unlock(&g_td.mutex);
    if (rc != 0) {
        dprintf("ERROR: mutex unlock failed, error code is %d!\n", rc);
        goto ERROROUT;
    }

    for (int j = 0; j < THREAD_NUM; j++) {
        /* Broadcast signals on the cond variable. */
        rc = pthread_cond_signal(&g_td.cond);
        if (rc != 0) {
            dprintf("ERROR: pthread condition failed, error code is %d!\n", rc);
            goto ERROROUT;
        }
    }

    sleep(1);

    /* Check whether all child threads are woken up. */
    if (g_wakenNum != THREAD_NUM) {
        dprintf("ERROR: not all threads awaken, only %d thread(s) awaken!\n", g_wakenNum);
        goto ERROROUT;
    }
    dprintf("all threads awaked\n");

    /* Join all  child threads, that is, wait for the end of all  child threads. */
    for (i = 0; i < THREAD_NUM; i++) {
        rc = pthread_join(thread[i], NULL);
        if (rc != 0) {
            dprintf("ERROR: pthread join failed, error code is %d!\n", rc);
            goto ERROROUT;
        }
    }
    dprintf("all threads join ok\n");

    /* Destroy the cond variable. */
    rc = pthread_cond_destroy(&g_td.cond);
    if (rc != 0) {
        dprintf("ERROR: pthread condition destroy failed, error code is %d!\n", rc);
        goto ERROROUT;
    }
    return 0;
ERROROUT:
    return -1;
}

Verification

The output is as follows:

pthread_create ok
all threads awaked
all threads join ok

Differences from the Linux Standard Library

The following describes the key differences between the standard library supported by the OpenHarmony kernel and the Linux standard library. For more differences, see the API document of the C library.

Process

The OpenHarmony user-mode processes support only static priorities, which range from 10 (highest) to 31 (lowest).
The OpenHarmony user-mode threads support only static priorities, which range from 0 (highest) to 31 (lowest).
The OpenHarmony process scheduling supports SCHED_RR only, and thread scheduling supports SCHED_RR or SCHED_FIFO.

Memory

Differences from Linux mmap

mmap prototype: void *mmap (void *addr, size_t length, int prot, int flags, int fd, off_t offset)

The lifecycle implementation of fd is different from that of Linux glibc. glibc releases the fd handle immediately after successfully invoking mmap for mapping. In the OpenHarmony kernel, you are not allowed to close the fd immediately after the mapping is successful. You can close the fd only after munmap is called. If you do not close fd, the OS reclaims the fd when the process exits.

Example

Linux:

int main(int argc, char *argv[])
{
    int fd;
    void *addr = NULL;
    ...
    fd = open(argv[1], O_RDONLY);
    if (fd == -1){
        perror("open");
        exit(EXIT_FAILURE);
    }
    addr = mmap(NULL, length, PROT_READ, MAP_PRIVATE, fd, offset);
    if (addr == MAP_FAILED) {
        perror("mmap");
        exit(EXIT_FAILURE);
    }
    close(fd);  /* OpenHarmony does not support closing fd immediately after the mapping is successful. */ 
    ...
    exit(EXIT_SUCCESS);
}

OpenHarmony:

int main(int argc, char *argv[])
{
    int fd;
    void *addr = NULL;
    ...
    fd = open(argv[1], O_RDONLY);
    if (fd == -1) {
        perror("open");
        exit(EXIT_FAILURE);
    }
    addr = mmap(NULL, length, PROT_READ, MAP_PRIVATE, fd, offset);
    if (addr == MAP_FAILED) {
        perror("mmap");
        exit(EXIT_FAILURE);
    }
    ...
    munmap(addr, length);
    close(fd);  /* Close fd after the munmap is canceled. */
    exit(EXIT_SUCCESS);
}

File System

System directories: You cannot modify system directories and device mount directories, which include /dev, /proc, /app, /bin, /data, /etc, /lib, /system, and /usr.

User directory: The user directory refers to the /storage directory. You can create, read, and write files in this directory, but cannot mount it to a device.

Except in the system and user directories, you can create directories and mount them to devices. Note that nested mount is not allowed, that is, a mounted folder and its subfolders cannot be mounted repeatedly. A non-empty folder cannot be mounted.

Signal

The default behavior for signals does not include STOP, CONTINUE, or COREDUMP.
A sleeping process (for example, a process enters the sleeping status by calling the sleep function) cannot be woken up by a signal. The signal mechanism does not support the wakeup function. The behavior for a signal can be processed only when the process is scheduled by the CPU.
After a process exits, SIGCHLD is sent to the parent process. The sending action cannot be canceled.
Only signals 1 to 30 are supported. The callback is invoked only once even if the same signal is received multiple times.