iot_taskpool.h

Go to the documentation of this file.

/*
 * IoT Common V1.1.0
 * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef IOT_TASKPOOL_H_
#define IOT_TASKPOOL_H_

/* The config header is always included first. */
#include "iot_config.h"

/* Standard includes. */
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

/* Task pool types. */
#include "types/iot_taskpool_types.h"

/*------------------------- Task Pool library functions --------------------------*/

/* @[declare_taskpool_createsystemtaskpool] */
IotTaskPoolError_t IotTaskPool_CreateSystemTaskPool( const IotTaskPoolInfo_t * pInfo );
/* @[declare_taskpool_createsystemtaskpool] */

/* @[declare_taskpool_getsystemtaskpool] */
IotTaskPool_t IotTaskPool_GetSystemTaskPool( void );
/* @[declare_taskpool_getsystemtaskpool] */

/* @[declare_taskpool_create] */
IotTaskPoolError_t IotTaskPool_Create( const IotTaskPoolInfo_t * pInfo,
                                       IotTaskPool_t * const pTaskPool );
/* @[declare_taskpool_create] */

/* @[declare_taskpool_destroy] */
IotTaskPoolError_t IotTaskPool_Destroy( IotTaskPool_t taskPool );
/* @[declare_taskpool_destroy] */

/* @[declare_taskpool_setmaxthreads] */
IotTaskPoolError_t IotTaskPool_SetMaxThreads( IotTaskPool_t taskPool,
                                              uint32_t maxThreads );
/* @[declare_taskpool_setmaxthreads] */

/* @[declare_taskpool_createjob] */
IotTaskPoolError_t IotTaskPool_CreateJob( IotTaskPoolRoutine_t userCallback,
                                          void * pUserContext,
                                          IotTaskPoolJobStorage_t * const pJobStorage,
                                          IotTaskPoolJob_t * const pJob );
/* @[declare_taskpool_createjob] */

/* @[declare_taskpool_createrecyclablejob] */
IotTaskPoolError_t IotTaskPool_CreateRecyclableJob( IotTaskPool_t taskPool,
                                                    IotTaskPoolRoutine_t userCallback,
                                                    void * pUserContext,
                                                    IotTaskPoolJob_t * const pJob );
/* @[declare_taskpool_createrecyclablejob] */

/* @[declare_taskpool_destroyrecyclablejob] */
IotTaskPoolError_t IotTaskPool_DestroyRecyclableJob( IotTaskPool_t taskPool,
                                                     IotTaskPoolJob_t job );
/* @[declare_taskpool_destroyrecyclablejob] */

/* @[declare_taskpool_recyclejob] */
IotTaskPoolError_t IotTaskPool_RecycleJob( IotTaskPool_t taskPool,
                                           IotTaskPoolJob_t job );
/* @[declare_taskpool_recyclejob] */

/* @[declare_taskpool_schedule] */
IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPool,
                                         IotTaskPoolJob_t job,
                                         uint32_t flags );
/* @[declare_taskpool_schedule] */

/* @[declare_taskpool_scheduledeferred] */
IotTaskPoolError_t IotTaskPool_ScheduleDeferred( IotTaskPool_t taskPool,
                                                 IotTaskPoolJob_t job,
                                                 uint32_t timeMs );
/* @[declare_taskpool_scheduledeferred] */

/* @[declare_taskpool_getstatus] */
IotTaskPoolError_t IotTaskPool_GetStatus( IotTaskPool_t taskPool,
                                          IotTaskPoolJob_t job,
                                          IotTaskPoolJobStatus_t * const pStatus );
/* @[declare_taskpool_getstatus] */

/* @[declare_taskpool_trycancel] */
IotTaskPoolError_t IotTaskPool_TryCancel( IotTaskPool_t taskPool,
                                          IotTaskPoolJob_t job,
                                          IotTaskPoolJobStatus_t * const pStatus );
/* @[declare_taskpool_trycancel] */

/* @[declare_taskpool_getjobstoragefromhandle] */
IotTaskPoolJobStorage_t * IotTaskPool_GetJobStorageFromHandle( IotTaskPoolJob_t job );
/* @[declare_taskpool_getjobstoragefromhandle] */

/* @[declare_taskpool_strerror] */
const char * IotTaskPool_strerror( IotTaskPoolError_t status );
/* @[declare_taskpool_strerror] */

#ifndef IOT_TASKPOOLS
#define IOT_TASKPOOLS                          ( 4 )
#endif

#ifndef IOT_TASKPOOL_JOBS_RECYCLE_LIMIT
    #define IOT_TASKPOOL_JOBS_RECYCLE_LIMIT    ( 8UL )
#endif

#ifndef IOT_TASKPOOL_JOB_WAIT_TIMEOUT_MS
    #define IOT_TASKPOOL_JOB_WAIT_TIMEOUT_MS    ( 60 * 1000UL )
#endif

#endif /* ifndef IOT_TASKPOOL_H_ */