-
Notifications
You must be signed in to change notification settings - Fork 6
/
Developers_Guide.txt
72 lines (46 loc) · 3.93 KB
/
Developers_Guide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
Developers' Guide for IP2Proxy C Library
===========================================
This guide explains the usage and the behavior of the below functions in the IP2Proxy C library
(1) IP2Proxy_set_lookup_mode
(2) IP2Proxy_close
(3) IP2Proxy_delete_shared_memory
Enumeration in IP2Proxy C Library
------------------------------------
enum IP2Proxy_lookup_mode {
IP2PROXY_FILE_IO,
IP2PROXY_CACHE_MEMORY,
IP2PROXY_SHARED_MEMORY
};
Functions in IP2Proxy C Library
-----------------------------------
Function (1)
int IP2Proxy_set_lookup_mode(IP2Proxy handler, enum IP2Proxy_lookup_mode);
loc - is of type IP2Proxy pointer, which is returned by function IP2Proxy_open.
IP2Proxy_lookup_mode - is of type IP2Proxy_lookup_mode enum. This argument specifies how the iplocation DB file will be loaded. It may be IP2PROXY_FILE_IO, IP2PROXY_CACHE_MEMORY and IP2PROXY_SHARED_MEMORY.
If IP2PROXY_FILE_IO is passed as argument, records will be searched directly from the DB file on the hard disk.
If IP2PROXY_CACHE_MEMORY is passed as argument, ip2proxy DB will be loaded into the memory and search will be performed on the DB present in the memory.
If IP2PROXY_SHARED_MEMORY is passed as argument, ip2proxy DB will be loaded into the memory and it will be shared across multiple processes. Please check at the end of this guide to know how this memory is shared and how to release the resource when it's no longer needed.
IP2Proxy_set_lookup_mode call must always be paired with a call to IP2Proxy_close; if IP2Proxy_set_lookup_mode is called more than once without calling IP2Proxy_close(), -1 will be returned.
RETURN value:
For any error IP2Proxy_set_lookup_mode will return -1, and will not set any errno variable.
Function (2)
uint32_t IP2Proxy_close(IP2Proxy *handler);
loc - is of type IP2Proxy pointer, which is returned by function IP2Proxy_open and it must be one used in IP2Proxy_set_lookup_mode.
Calling this function will close the DB file and free the allocated cache memory or detach from the shared memory. (Shared memory will not be deleted from this call.)
RETURN value:
This function always return zero.
Function (3)
void IP2Proxy_delete_shared_memory();
This function will delete the shared memory created from IP2Proxy_set_lookup_mode in Linux, Unix and MAC OS. In Windows, it's just an empty function call. Please read the next section.
RETURN value:
void
Note: Key used for the shared memory is "/IP2Proxy_Shm", please make sure it does not conflict with any other shared memory.
IP2PROXY_SHARED_MEMORY – If IP2Proxy_set_lookup_mode is called with this as the second argument, shared memory will be created if it does not already exists else the existing shared memory will be read instead.
In Windows:
Whenever the IP2Proxy_close() function is called by the sole process attached to the shared memory, then the DB file will be closed and the shared memory will be deleted.
If there are other processes attached to the shared memory, then the caller process will just detach itself from the shared memory while leaving the shared memory intact.
Call to IP2Proxy_delete_shared_memory in Windows have no effect as Windows does not support shared memory.
In Linux, Unix and MacOS:
Call to IP2Proxy_close will not deleted the shared memory, it will only detach the process from using that memory. To delete the shared memory IP2Proxy_delete_shared_memory() must be called.
When IP2Proxy_delete_shared_memory() function is called, and if any other process(es) is attached to shared memory, it will only delete the name of the shared memory but the other process(es) will continue to use memory and memory will be freed only after last attached process is detached from it.
After calling IP2Proxy_delete_shared_memory(), the next call to IP2Proxy_set_lookup_mode() with IP2PROXY_SHARED_MEMORY option will result in a new shared memory and will not reuse the old one if one exists and used by any other process. Please refer shm_open and shm_unlink man pages for more info.