{ "content": [ { "type": "text", "text": "# IPC::ShareLite (perldoc)\n\n## NAME\n\nIPC::ShareLite - Lightweight interface to shared memory\n\n## SYNOPSIS\n\nuse IPC::ShareLite;\nmy $share = IPC::ShareLite->new(\n-key => 1971,\n-create => 'yes',\n-destroy => 'no'\n) or die $!;\n$share->store( \"This is stored in shared memory\" );\nmy $str = $share->fetch;\n\n## DESCRIPTION\n\nIPC::ShareLite provides a simple interface to shared memory, allowing data to be efficiently\ncommunicated between processes. Your operating system must support SysV IPC (shared memory and\nsemaphores) in order to use this module.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **PERFORMANCE**\n- **PORTABILITY**\n- **AUTHOR**\n- **CREDITS**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "IPC::ShareLite", "section": "", "mode": "perldoc", "summary": "IPC::ShareLite - Lightweight interface to shared memory", "synopsis": "use IPC::ShareLite;\nmy $share = IPC::ShareLite->new(\n-key => 1971,\n-create => 'yes',\n-destroy => 'no'\n) or die $!;\n$share->store( \"This is stored in shared memory\" );\nmy $str = $share->fetch;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "ipc", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/ipc/2/json" }, { "name": "shmget", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/shmget/2/json" }, { "name": "semget", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/semget/2/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 11, "subsections": [] }, { "name": "DESCRIPTION", "lines": 51, "subsections": [] }, { "name": "METHODS", "lines": 137, "subsections": [] }, { "name": "PERFORMANCE", "lines": 28, "subsections": [] }, { "name": "PORTABILITY", "lines": 14, "subsections": [] }, { "name": "AUTHOR", "lines": 7, "subsections": [] }, { "name": "CREDITS", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "IPC::ShareLite - Lightweight interface to shared memory\n", "subsections": [] }, "VERSION": { "content": "This document describes IPC::ShareLite version 0.17\n", "subsections": [] }, "SYNOPSIS": { "content": "use IPC::ShareLite;\n\nmy $share = IPC::ShareLite->new(\n-key => 1971,\n-create => 'yes',\n-destroy => 'no'\n) or die $!;\n\n$share->store( \"This is stored in shared memory\" );\nmy $str = $share->fetch;\n", "subsections": [] }, "DESCRIPTION": { "content": "IPC::ShareLite provides a simple interface to shared memory, allowing data to be efficiently\ncommunicated between processes. Your operating system must support SysV IPC (shared memory and\nsemaphores) in order to use this module.\n\nIPC::ShareLite provides an abstraction of the shared memory and semaphore facilities of SysV\nIPC, allowing the storage of arbitrarily large data; the module automatically acquires and\nremoves shared memory segments as needed. Storage and retrieval of data is atomic, and locking\nfunctions are provided for higher-level synchronization.\n\nIn many respects, this module is similar to IPC::Shareable. However, IPC::ShareLite does not\nprovide a tied interface, does not (automatically) allow the storage of variables, and is\nwritten in C for additional speed.\n\nConstruct an IPC::ShareLite object by calling its constructor:\n\nmy $share = IPC::ShareLite->new(\n-key => 1971,\n-create => 'yes',\n-destroy => 'no'\n) or die $!;\n\nOnce an instance has been created, data can be written to shared memory by calling the store()\nmethod:\n\n$share->store(\"This is going in shared memory\");\n\nRetrieve the data by calling the fetch() method:\n\nmy $str = $share->fetch();\n\nThe store() and fetch() methods are atomic; any processes attempting to read or write to the\nmemory are blocked until these calls finish. However, in certain situations, you'll want to\nperform multiple operations atomically. Advisory locking methods are available for this purpose.\n\nAn exclusive lock is obtained by calling the lock() method:\n\n$share->lock();\n\nHappily, the lock() method also accepts all of the flags recognized by the flock() system call.\nSo, for example, you can obtain a shared lock like this:\n\n$share->lock( LOCKSH );\n\nOr, you can make either type of lock non-blocking:\n\n$share->lock( LOCKEX|LOCKNB );\n\nRelease the lock by calling the unlock() method:\n\n$share->unlock;\n", "subsections": [] }, "METHODS": { "content": "\"new($key, $create, $destroy, $exclusive, $mode, $flags, $size)\"\nThis is the constructor for IPC::ShareLite. It accepts both the positional and named parameter\ncalling styles.\n\n$key is an integer value used to associate data between processes. All processes wishing to\ncommunicate should use the same $key value. $key may also be specified as a four character\nstring, in which case it will be converted to an integer value automatically. If $key is\nundefined, the shared memory will not be accessible from other processes.\n\n$create specifies whether the shared memory segment should be created if it does not already\nexist. Acceptable values are 1, 'yes', 0, or 'no'.\n\n$destroy indicates whether the shared memory segments and semaphores should be removed from the\nsystem once the object is destroyed. Acceptable values are 1, 'yes', 0, or 'no'.\n\nIf $exclusive is true, instantiation will fail if the shared memory segment already exists.\nAcceptable values are 1, 'yes', 0, or 'no'.\n\n$mode specifies the permissions for the shared memory and semaphores. The default value is 0666.\n\n$flags specifies the exact shared memory and semaphore flags to use. The constants IPCCREAT,\nIPCEXCL, and IPCPRIVATE are available for import.\n\n$size specifies the shared memory segment size, in bytes. The default size is 65,536 bytes,\nwhich is fairly portable. Linux, as an example, supports segment sizes of 4 megabytes.\n\nThe constructor croaks on error.\n\n\"store( $scalar )\"\nThis method stores $scalar into shared memory. $scalar may be arbitrarily long. Shared memory\nsegments are acquired and released automatically as the data length changes. The only limits on\nthe amount of data are the system-wide limits on shared memory pages (SHMALL) and segments\n(SHMMNI) as compiled into the kernel.\n\nThe method raises an exception on error.\n\nNote that unlike IPC::Shareable, this module does not automatically allow references to be\nstored. Serializing all data is expensive, and is not always necessary. If you need to store a\nreference, you should employ the Storable module yourself. For example:\n\nuse Storable qw( freeze thaw );\n...\n$hash = { red => 1, white => 1, blue => 1 };\n$share->store( freeze( $hash ) );\n...\n$hash = thaw( $share->fetch );\n\n\"fetch\"\nThis method returns the data that was previously stored in shared memory. The empty string is\nreturned if no data was previously stored.\n\nThe method raises an exception on error.\n\n\"lock( $type )\"\nObtains a lock on the shared memory. $type specifies the type of lock to acquire. If $type is\nnot specified, an exclusive read/write lock is obtained. Acceptable values for $type are the\nsame as for the flock() system call. The method returns true on success, and undef on error. For\nnon-blocking calls (see below), the method returns 0 if it would have blocked.\n\nObtain an exclusive lock like this:\n\n$share->lock( LOCKEX ); # same as default\n\nOnly one process can hold an exclusive lock on the shared memory at a given time.\n\nObtain a shared lock this this:\n\n$share->lock( LOCKSH );\n\nMultiple processes can hold a shared lock at a given time. If a process attempts to obtain an\nexclusive lock while one or more processes hold shared locks, it will be blocked until they have\nall finished.\n\nEither of the locks may be specified as non-blocking:\n\n$share->lock( LOCKEX|LOCKNB );\n$share->lock( LOCKSH|LOCKNB );\n\nA non-blocking lock request will return 0 if it would have had to wait to obtain the lock.\n\nNote that these locks are advisory (just like flock), meaning that all cooperating processes\nmust coordinate their accesses to shared memory using these calls in order for locking to work.\nSee the flock() call for details.\n\nLocks are inherited through forks, which means that two processes actually can possess an\nexclusive lock at the same time. Don't do that.\n\nThe constants LOCKEX, LOCKSH, LOCKNB, and LOCKUN are available for import:\n\nuse IPC::ShareLite qw( :lock );\n\nOr, just use the flock constants available in the Fcntl module.\n\n\"unlock\"\nReleases any locks. This is actually equivalent to:\n\n$share->lock( LOCKUN );\n\nThe method returns true on success and undef on error.\n\n\"version\"\nEach share has a version number that incrementents monotonically for each write to the share.\nWhen the share is initally created its version number will be 1.\n\nmy $numwrites = $share->version;\n\n\"key\"\nGet a share's key.\n\nmy $key = $share->key;\n\n\"create\"\nGet a share's create flag.\n\n\"exclusive\"\nGet a share's exclusive flag.\n\n\"flags\"\nGet a share's flag.\n\n\"mode\"\nGet a share's mode.\n\n\"size\"\nGet a share's segment size.\n\n\"numsegments\"\nGet the number of segments in a share. The memory usage of a share can be approximated like\nthis:\n\nmy $usage = $share->size * $share->numsegments;\n\n$usage will be the memory usage rounded up to the next segment boundary.\n\n\"destroy\"\nGet or set the share's destroy flag.\n", "subsections": [] }, "PERFORMANCE": { "content": "For a rough idea of the performance you can expect, here are some benchmarks. The tests were\nperformed using the Benchmark module on a Cyrix PR166+ running RedHat Linux 5.2 with the 2.0.36\nkernel, perl 5.00502 using perl's malloc, and the default shared memory segment size. Each test\nwas run 5000 times.\n\nDATA SIZE (bytes) TIME (seconds) Op/Sec\n\nstore 16384 2 2500\nfetch 16384 2 2500\n\nstore 32768 3 1666\nfetch 32768 3 1666\n\nstore 65536 6 833\nfetch 65536 5 1000\n\nstore 131072 12 416\nfetch 131072 12 416\n\nstore 262144 28 178\nfetch 262144 27 185\n\nstore 524288 63 79\nfetch 524288 61 81\n\nMost of the time appears to be due to memory copying. Suggestions for speed improvements are\nwelcome.\n", "subsections": [] }, "PORTABILITY": { "content": "The module should compile on any system with SysV IPC and an ANSI C compiler, and should compile\ncleanly with the -pedantic and -Wall flags.\n\nThe module has been tested under Solaris, FreeBSD, and Linux. Testing on other platforms is\nneeded.\n\nIf you encounter a compilation error due to the definition of the semun union, edit the top of\nsharestuff.c and undefine the semun definition. And then please tell me about it.\n\nI've heard rumors that a SysV IPC interface has been constructed for Win32 systems. Support for\nit may be added to this module.\n\nIPC::ShareLite does not understand the shared memory data format used by IPC::Shareable.\n", "subsections": [] }, "AUTHOR": { "content": "Copyright 1998-2002, Maurice Aubrey . All rights reserved.\n\nThis release by Andy Armstrong .\n\nThis module is free software; you may redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] }, "CREDITS": { "content": "Special thanks to Benjamin Sugars for developing the IPC::Shareable module.\n\nSee the Changes file for other contributors.\n", "subsections": [] }, "SEE ALSO": { "content": "IPC::Shareable, ipc(2), shmget(2), semget(2), perl.\n", "subsections": [] } } } }