SCF will execute a function for you when the function receives a triggering request. Instance is the resource for SCF to execute the request. SCF will allocate resources based on the function configuration information (such as memory size) and launch one or multiple instances to process the function request. The SCF platform is responsible for the creation, management, and deletion of all function runtime instances, and you have no permissions to manage them.
The lifecycle of an instance is depicted as follows:
Starting instance
If there is no running instance when a request arrives, the request will trigger the startup of an instance. Instance startup usually takes some time, which adds extra time to the invocation that triggers the instance startup. Generally, instance startup is triggered only when a function is invoked for the first time, updated, or invoked again after a long period of inactivity.
The time consumed by instance startup will be reflected in the Coldstart field in the Execution LogInit Report or Provisioned Report line of the function.
You can use the provisioned concurrency feature to start instances in advance to avoid triggering the instance startup when the function request arrives.
The instance startup time is limited by the function's initialization timeout period. If the former is longer than the latter, instance startup will fail. You can accelerate instance startup or increase the initialization timeout period accordingly as detailed below.
Method to accelerate the three phases of instance startup:
Code Preparation: The platform retrieves the function code, layers, or images uploaded by the user to prepare for function execution. The time consumed in code preparation is directly proportional to the size of the code package, layers, or images. It is recommended to streamline the code package as much as possible, retaining only the necessary code files and dependencies for function execution, to minimize code preparation time. The time consumed in code preparation will be reflected in the PullCode field in the Execution LogInit Report or Provisioned Report line of the function.
Runtime Initialization: The platform prepares the runtime environment required for function execution based on the user's function configuration. The time consumed in runtime initialization will be reflected in the InitRuntime field in the Execution LogInit Report or Provisioned Report line of the function.
Function Code Initialization: The time consumed in code initialization is directly proportional to the complexity of the code logic. It is recommended to optimize the code logic as much as possible to minimize code initialization time. The time consumed in function code initialization will be reflected in the InitFunction field in the Execution LogInit Report or Provisioned Report line of the function.
For event functions with code deployment: During the instance startup phase, the code logic preceding the execution method configured in the function will be executed (for example, if the entry function is main_handler, all code logic before main_handler will be executed).
Code deployment-based HTTP-triggered function: the bootstrap file scf_bootstrap and the code logic before listening port 9000 will be executed during instance startup.
For functions deployed with images: Event-triggered functions will execute the code logic preceding the execution method configured in the function; HTTP-triggered functions will execute the bootstrap file scf_bootstrap and the code logic before listening to port 9000.
Instance reuse
In order to minimize the additional time caused by instance startup, the platform will try to reuse the instance for subsequent invocations. After the instance processes the function request, it will be stored for a period of time according to the actual situation of the platform for next invocations and will be used first during this period.
The meaning of instance reuse is as follows:
All declarations outside the execution method part in your code remain initialized and can be reused directly when the function is invoked again. For example, if a database connection is established in your function code, the original connection can be used directly when the container is reused. You can add logic to your code to check whether a connection already exists before creating a new one.
Each container provides some disk space in the /tmp directory. The contents of this directory are retained when the container is retained, providing a temporary cache that can be used for multiple invocations. It is possible to use the contents of the disk directly when the function is invoked again. You can add extra code to check whether such data is in the cache.
Note
Do not assume that the instance is always reused in the function code, because reuse is related to the single actual invocation, and it cannot be guaranteed whether a new instance will be created or an existing one will be reused.
Repossessing instance
The platform will repossess instances that have not processed requests for a certain period of time.
Temporary Disk Space
During the execution of SCF functions, there is a 512MB temporary disk space /tmp available. Users can perform some read and write operations in this space during code execution, and can also create subdirectories. However, this data may not be retained after the function execution is completed. Therefore, if you need to persistently store the data generated during execution, please use Object Storage COS or external persistent storage such as Redis/Memcached.
Call Types
The SCF platform supports both sync and async calls of functions.
Sync invocation
A synchronous function call will continue to wait for the return of the execution result after the call request is issued.
Async invocation
Async call will only send the request and get the request ID of the current request, but not wait for the result.
When an async invocation occurs, the async event will be placed in the async queue built in SCF and then consumed by the event execution function in the async queue. Async queues have the following restrictions:
Async queues are at the trigger level, and one function trigger has one queue.
An async event can be retained in a queue for up to 6 hours.
There can be up to 100,000 messages in an async queue.
The retry policy may vary by async queue. For more information, please see Retry Policy.
Defining function invocation type
The call type is independent of the configuration of the function itself and can only be controlled when the function is called.
In the following call scenarios, you can freely define the call type of the function:
Your application calls the SCF function. If you need a synchronous call, use the synchronous call interface InvokeFunction; if you need an asynchronous call, use the Invoke interface and pass in the parameter invokeType=Event.
The SCF function is manually invoked (with API or CLI) for testing. The parameters for the invocation are the same as above.
When you use other Tencent Cloud services as event sources, the call type of the cloud service is predefined:
For quotas and environmental restrictions related to function usage, please refer to Quotas and Limitations.
Function Concurrency
The function concurrency is the number of executions of the function code in any given period of time. For the current SCF function, the request is executed once each time an event is published. Therefore, the number of events (i.e., requests) published by the trigger affects the function concurrency. You can use the formula below to estimate the total number of concurrent function instances.
Requests per second * function execution duration (in seconds)
For instance, consider a function that processes COS events. Assuming the function takes an average of 0.2 seconds (i.e., 200 milliseconds) to execute, and COS publishes 300 requests per second to the function. This would concurrently generate 300 * 0.2 = 60 function instances.
Concurrency Restrictions
By default, SCF imposes certain concurrency limits on each function. You can view the Concurrency Management to understand the current concurrency limit of the function.
If an invocation causes the function's concurrency to exceed the default limit, the invocation will be blocked and SCF will not execute it. Depending on the function's invocation method, the handling of restricted invocations may vary:
Sync invocation: if the function is restricted when invoked synchronously, a 432 error will be returned directly.
Async invocation: if the function is restricted when invoked asynchronously, SCF will retry the restricted event according to a certain policy.
Execution Environment and Available Libraries
The current SCF execution environment is built based on the following:
Standard CentOS 7.2
If you need to include executable binary files, dynamic libraries, or static libraries in your code, ensure they are compatible with this execution environment. Depending on the language environment, there are basic libraries and additional installed libraries under the SCF execution environment. You can view the additional libraries installed in the environment in the language instructions:
Serverless Cloud Function (SCF) provides two deployment methods of code deployment and image deployment and supports two function types of event-triggered function and HTTP-triggered function. Different deployment methods and function types require different specifications during code development. This document describes the writing specifications and related concepts of event-triggered function in code deployment. For more information on image deployment and HTTP-triggered function, please see the corresponding documents.
SCF event-triggered function
There are three basic concepts in SCF event-triggered functions: execution method, function input parameters, and function return. These concepts correspond to the following in typical project development:
Execution method: corresponds to the main function of the project and is the starting point of program execution.
Function Input Parameters: These are the typical function input parameters. However, in the SCF environment, the input parameters of the entry function are fixed by the platform. For more details, see Function Input Parameters.
Function return: corresponds to the returned value of the main function in the project. After the function returns, the code execution ends.
Execution Method
When the SCF platform invokes a cloud function, it first seeks the execution method as the entry point to execute the user's code. At this point, users need to set it in the format of filename.executionMethodName.
For instance, if the user sets the execution method as index.handler, the SCF platform will first seek the index file in the code package and start executing the handler method found in that file.
Within the execution method, users can process the input parameters of the entry function and freely call other methods in the code. The execution of an SCF function ends when the entry function has finished executing or if there is an exception during execution.
Function input parameters
Function input parameters refer to the content passed to the function when it is triggered and invoked. Typically, function input parameters include two parts: event and context. However, depending on the development language and environment, the number of input parameters may vary. For more details, see Development Language Description.
event
Context input parameters
Usage
The event parameter is of dict type and contains the basic information that triggers the function. It can be in a platform-defined or custom format. After the function is triggered, the event can be processed inside the code.
These two SCF trigger methods correspond to two event formats:
Triggering function execution via TencentCloud API:
A dict type parameter can be customized between the caller and the function code. The caller inputs data according to the defined format, and the function code retrieves data in the same format.
Example:
Define a dict type data structure {"key":"XXX"}. When the caller inputs data {"key":"abctest"}, the function code can obtain the value 'abctest' through event[key].
Triggering function execution via a trigger:
SCF is integrated with various cloud services such as API Gateway, COS, and Ckafka. Function execution can be triggered by binding the corresponding cloud service triggers to the function. When a trigger initiates a function, the event is passed to the function as an event parameter in a predefined, unchangeable format. You can write code based on this format and retrieve information from the event parameter.
Example:
When a function is triggered by COS, the specific information of the object storage bucket and file is passed to the event parameter in JSON format. By parsing the event information in the function code, the trigger event can be processed.
Usage
context is an input parameter provided by the SCF platform. It is passed to the execution method, by parsing which the code can get the runtime environment and related information of the current request.
Use Instructions
The fields and descriptions of the context input parameter provided by SCF are as follows:
Field Name
Description
memory_limit_in_mb
Function Memory Configuration
time_limit_in_ms
Function Execution Timeout Period
request_id
Function Execution Request ID
environment
Function Namespace Information
environ
Function Namespace Information
function_version
Function Version Details
function_name
Function Name
namespace
Function Namespace Information
tencentcloud_region
Function's Region
tencentcloud_appid
Tencent Cloud Account's APPID for the Function
tencentcloud_uin
Tencent Cloud Account ID Associated with the Function
Note
To ensure compatibility, the context retains the description methods for namespaces at different stages of SCF. The structure of the context will expand with the development iterations of the SCF platform.
You can print the context information through the standard output statement in the function code. Take the python runtime environment as an example:
# -*- coding: utf8 -*-
import json
def main_handler(event, context):
print(context)
return("Hello World")
The following context information can be obtained:
After understanding the basic usage of event and context input parameters, you should pay attention to the following points when writing function code:
To ensure uniformity across various development languages and environments, both event and context input parameters are encapsulated using the JSON data format.
Different triggers pass different data structures when triggering functions. For more information, please refer to Function Trigger Description.
If the function does not need any input, you can ignore the event and context parameters in your code.
Function Return
The SCF platform will get the returned value after the function is executed and handle according to different trigger type as listed below.
Trigger Method
Handling Method
Synchronous Trigger
The function is triggered synchronously when invoked through the API Gateway or TencentCloud APIs.
For functions triggered synchronously, the SCF platform will not return the trigger result during execution.
Upon completion of the function execution, the SCF platform encapsulates the function's return value into a JSON format and returns it to the caller.
Asynchronous Trigger
For cloud functions triggered asynchronously, the SCF platform will return the trigger request ID upon receiving the trigger event.
Upon completion of the function execution, the return value is encapsulated into a JSON format and stored in the logs.
Upon completion of the function execution, users can retrieve the return value of the asynchronously triggered function by querying the logs with the returned request ID.
When the code in a function returns a specific value, it usually returns a specific data structure; for example:
Runtime Environment
Return Data Structure Type
Python
Simple or dict data structure
Node.js
JSON Object
PHP
Array structure
GO
Simple data structure or struct with JSON description
To ensure uniformity across various development languages and environments, the function return will be uniformly encapsulated in JSON data format. Upon receiving the return value of the function from the above runtime environment, the SCF platform will convert the returned data structure into JSON and return the JSON content to the caller.
Note
You should ensure that the returned value of the function can be converted to JSON format. If the object is returned directly and there is no JSON conversion method, SCF will fail when executing JSON conversion and prompt an error.
For example, the returned value in the above runtime environment does not need to be converted to JSON format before it is returned; otherwise, the output string will be converted again.
Exception Handling
If an exception occurs during testing and executing a function, the SCF platform will handle the exception as much as possible and write the exception information into the log. Exceptions generated by function execution include caught exceptions (handled errors) and uncaught exceptions (unhandled errors).
Solutions
You can log in to the SCF console and follow the steps below to test exception handling:
1. Create a function and copy the following function code without adding any triggers.
2. Click Test in the console and select the "Hello World" test sample for testing.
This document provides the following three ways to throw exceptions, and you can choose how to handle exceptions in the code based on your actual needs.
Throw exceptions explicitly
Inherit the `Exception` class
Use the `Try` statement to capture errors
Example
defalways_failed_handler(event,context):
raise Exception ('I failed!')
Note
This function will raise an exception during its execution and return the following error message. The SCF platform will record this error message in the function log.
File "/var/user/index.py", line 2, in always_failed_handler
You can define how to handle errors in your code to ensure the robustness and scalability of your application.
Example
defcreate_user(event):
try:
createUser (event [username],event [pwd])
except UserNameAlreadyExistsException,e://catch error and do something
Explanation
You can define how to handle errors in your code to ensure the robustness and scalability of your application.
Returns error message
When exception handling and error capturing are not performed in the user's code logic, the SCF platform will attempt to capture errors as much as possible. For instance, if a user function suddenly crashes during execution and the platform is unable to capture the error, the system will return a generic error message.
The table below displays some common errors that may occur during code execution:
Error Scenario
Error Message
raise is used to throw an exception
{File "/var/user/index.py", line 2, in always_failed_handler raise Exception ('xxx') Exception: xxx}
The handler does not exist
{'module' object has no attribute 'xxx'}
The dependent module does not exist
{global name 'xxx' is not defined}
Timed out
{"time out"}
Log
SCF platform stores all function call records and all outputs from the function code in the logs. Please use the print output statement or log statement in the programming language to generate output logs for easy debugging and troubleshooting. For more details, see Log Management.
Precautions
Given the characteristics of SCF, you must write your function code in a stateless style. Local file storage and other state features within the function lifecycle will be destroyed after the function call ends. Therefore, it is recommended to store persistent states in relational databases like TencentDB, object storage COS, cloud database Memcached, or other cloud storage services.
Development Process
For more information on the function development process, please see Getting Started.
